mirror of
https://github.com/outbackdingo/step-ca-webui.git
synced 2026-01-27 18:20:22 +00:00
163 lines
4.8 KiB
Markdown
163 lines
4.8 KiB
Markdown
# WIP
|
|
# IT NOT WORKS AND IS ABANDONED/PAUSED FOR NOW
|
|
# 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](docs/architecture-overview.puml)
|
|
|
|
|
|
### 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](docs/core-api.yaml) for Core component OpenAPI specification.
|
|
|
|
### Class Diagram
|
|
|
|
Describes the class structure of the application's python components. [Source PUML code](docs/class-diagram.puml)
|
|
|
|
|
|
### 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
|