About

The project is a web-based interface for managing a smallstep step-ca Certificate Authority. In other words, it's shell wrapper for step-ca CLI. It provides a user-friendly way to handle certificate operations, view logs, and manage server access. The system is designed with security in mind, separating components with different privileges and logging all actions for audit purposes. Written in python.

Main Functions

Certificate Management

All on one page

• List certificates
• Generate new certificates (with options for key type, duration, etc.)
• Revoke certificates
• Renew certificates

Logging and Monitoring

• Every action such as certificate generation, revocation etc shows it's related logs immediately to user in the UI
• Every action shows shell command that it will execute
• Retrieve logs with filtering

Web UI

• Dashboard + Certificate Management Page
• Logs and Command History Page

Auto Setup

1. Install & setup step-ca on host
2. Create initial root certificate
3. Prepare certificates for mTLS
4. Run docker-compose.uml

Security Features

• Separation of privileged sudo setup process from main application
• Main application runs in container with limited permissions, only step-ca on host is available
• Web UI is in separate basic docker container
• Input value restrictions (eg letters and numbers only for key name)
• Input sanitization in CLIWrapper to prevent command injection
• Use of subprocess module with shell=True for secure command execution
• Logging of all command executions for audit purposes
• Configuration loaded from a separate file
• Use of AppArmor/SELinux profiles for main container
• mTLS for secure communication between web frontend and main app
• Authentication via auth proxy
• Web Firewall
• Internal API keys via secret management
• Security events email alerts
• Read-only filesystem for containers

Tech Stack

• Python
• Flask
• Docker
• Caddy (reverse proxy)
• Authelia (auth proxy)
• Bunkerweb (web firewall)
• step-ca CLI

Additional Notes

• Type hints/dataclasses are used throughout for better code clarity and error checking
• The design allows for easy extension and maintenance
• The AutoSetup component (for initial installation and setup) is designed to be run separately with elevated privileges
• Web app auth is provided via third-party proxy, not required for this project

---

Architecture

Overview

Diagram describes general architecture of the application. Source PUML code

Logging

Convenient logging allows system to be transparent about underlying CLI wrapping. This is important due to unstable nature of CLI tools.

• Logs are stored in file (in future can be stored in database)
• Escaping for JSON serialization
• Log rotation and cleanup support
• Custom logger class for logging
• Special API endpoint for fetching logs, with filtering and pagination
• Scoped logging (trace_id) implemented for tracking actions across multiple log entries

Core API

See docs/core-api.yaml for Core component OpenAPI specification.

Class Diagram

Describes the class structure of the application's python components. Source PUML code

File structure

This is final file structure of the project:

project_root/
│
├── docker-compose.yml
├── README.md
├── requirements.txt
│
├── core/
│   ├── api_server.py
│   ├── certificate_manager.py
│   ├── Dockerfile
│   ├── main.py
│   └── requirements.txt
│
├── docs/
│   ├── architecture-overview.paml
│   ├── class-diagram.puml
│   └── core-api.yaml
│
├── front/
│   ├── api_client.py
│   ├── Dockerfile
│   ├── main.py
│   ├── requirements.txt
│   └── html/
│       ├── dashboard.html.j2
│       ├── logs.html.j2
│       ├── styles.css
│       └── script.js
│
├── shared/
│   ├── __init__.py
│   ├── api_models.py
│   ├── cli_wrapper.py
│   ├── db_logger.py
│   ├── logger.py
│   └── models.py
│
├── auto_setup/
│   ├── auto_setup.py
│   └── requirements.txt
│
└── config/
    ├── app_config.yml
    └── logging_config.yml

---

TODO

• Adjust class diagram after finalizing the project
• Prevent simultaneous actions calls