CAAMS Enterprise

A self-hosted, multi-user GRC platform. Select a security framework, map your tool stack, and run an auditor-ready compliance assessment — with full lifecycle management, evidence collection, findings tracking, RFIs, audit log, and multi-format exports.

Quick Start

1. Install dependencies

pip install -r requirements.txt

2. Seed the database

Loads all framework definitions and the tool catalog. Safe to re-run — skips anything already present.

python seed.py

3. Set the secret key

CAAMS requires a secret key to sign JWT tokens. The app will refuse to start without it.

export CAAMS_SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"

Add that line to your shell profile or a .env file for persistent dev setups.

4. Generate TLS certificates

The default configuration serves over HTTPS. Self-signed certificates are required for local development.

mkdir -p certs
openssl req -x509 -newkey rsa:4096 \
  -keyout certs/key.pem -out certs/cert.pem \
  -sha256 -days 3650 -nodes \
  -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

5. Start the server

bash start.sh
# → https://localhost:8443

First-Run Setup

On first visit, the UI shows a setup screen to create the initial admin account. You can also do this via the API:

curl -X POST https://localhost:8443/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "YourPassword"}'

This endpoint is only available when no users exist. After setup, it is permanently disabled.

Features

Supported Frameworks

Additional frameworks can be added by dropping a JSON file into app/data/. See Adding Frameworks.

Usage Guide

Creating an assessment

1. Click Assessments → New Assessment
2. Enter a name, pick a framework, add scope notes, and optionally set a recurrence schedule
3. Click Submit — the assessment opens in Draft status

From the assessment detail view, switch to the Controls tab and click Edit on any control to set notes, evidence links, ownership, and override status.

Evidence

Upload files on the Evidence tab. Files are associated with a specific control, given a description and expiry date, and can be approved or rejected by admins. Full evidence packages (PDF report + all files + manifest CSV) are downloadable as a ZIP.

Findings

Log issues on the Findings tab. Each finding has severity (critical → informational), status, and a remediation owner + target date. Closing a finding automatically stamps the close date.

Requests for Information (RFIs)

Create RFIs with priority levels and due dates. Assignees respond inline; admins close RFIs when resolved. Useful for coordinating evidence requests with external auditors.

Dashboard

The Dashboard shows org-wide posture across all active assessments:

• Overall compliance score and per-framework bar chart
• Open findings by severity (doughnut chart)
• Overdue controls count
• Assessments due for renewal in the next 30 days
• Assessment pipeline (draft / in_review / approved count)

Assessment Lifecycle

Each transition creates a signed-off record with comments, visible on the Audit Log tab.

Coverage Scoring

CAAMS uses partial-credit scoring rather than a simple pass/fail:

Authentication

CAAMS uses JWT-based authentication (HS256, pure-Python — no C dependencies). All API endpoints except /health and /auth/setup require a valid bearer token.

Logging in

curl -X POST https://localhost:8443/auth/login \
  -d "username=admin&password=YourPassword"
# returns {"access_token": "...", "token_type": "bearer", "role": "admin"}

# Pass the token in subsequent requests:
curl https://localhost:8443/assessments \
  -H "Authorization: Bearer <token>"

Tokens expire after 8 hours. Login is rate-limited to 10 attempts per minute per IP.

Roles

Roles are assigned at account creation and enforced on every endpoint.

API Tokens

For CI/CD pipelines and external integrations, create long-lived API tokens via Admin → API Tokens or via the API:

curl -X POST https://localhost:8443/api-tokens \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-pipeline", "expires_in_days": 365}'

API Reference

The full interactive Swagger UI is available at /docs on any running CAAMS instance.

Auth

Frameworks & Tools

Assessments

Controls

Evidence

Findings & RFIs

Exports

Dashboard, Audit Log & Misc

Exports

XLSX Workbook GET /assessments/{id}/export

PDF Report GET /assessments/{id}/export/pdf

• Branded cover page with assessment name, framework, and date
• Executive summary with aggregate metrics
• Tools-in-scope table
• Color-coded per-control coverage table
• Findings table with severity

Evidence ZIP Package GET /assessments/{id}/export/evidence-package

• Complete PDF report included at the root
• All evidence files grouped by control ID in subdirectories
• Manifest CSV mapping each file to its control, description, uploader, and approval status

Environment Variables

In production these are loaded from /etc/caams.env by the systemd unit (created automatically by install_service.sh).

Production Deployment

install_service.sh automates a full production install on any systemd-based Linux host (tested on Ubuntu 22.04+).

sudo bash install_service.sh

The installer:

1. Verifies prerequisites (systemctl, python3)
2. Copies the app to /opt/caams/
3. Creates a virtualenv at /opt/caams/venv and installs all dependencies
4. Requires TLS certificates at certs/cert.pem + certs/key.pem — prints generation instructions and aborts if missing
5. Creates a dedicated caams system user and group
6. Generates a random CAAMS_SECRET_KEY and writes it to /etc/caams.env (readable only by root and the service account)
7. Seeds the database if caams.db does not exist
8. Writes the systemd unit to /etc/systemd/system/caams.service, enables, and starts it

sudo systemctl status caams
sudo journalctl -u caams -f              # live log stream
sudo tail -f /opt/caams/logs/app.log     # app events only

# Swap in a CA-signed certificate:
sudo cp your-cert.pem /opt/caams/certs/cert.pem
sudo cp your-key.pem  /opt/caams/certs/key.pem
sudo systemctl restart caams

Logging

Two rotating log files are written to logs/ (10 MB per file, 5 backups). All entries also appear in stdout / journalctl -u caams.

logs/access.log — every HTTP request

2026-02-21 12:34:56 | 10.0.0.1 | POST /auth/login | 200 | 13ms
2026-02-21 12:34:57 | 10.0.0.1 | GET /assessments/5/results | 200 | 87ms

logs/app.log — application events

2026-02-21 12:34:55 | INFO    | STARTUP | CAAMS v1.0.0 | database ready
2026-02-21 12:34:56 | WARNING | LOGIN failed | username=badguy | ip=10.0.0.3
2026-02-21 12:34:57 | INFO    | LOGIN success | user=admin | role=admin | ip=10.0.0.1
2026-02-21 12:35:10 | INFO    | ASSESSMENT created | id=5 | name=Q1 Audit | by=admin
2026-02-21 12:36:00 | INFO    | LIFECYCLE | assessment=5 | action=approve | by=admin

Adding Frameworks

Create a JSON file in app/data/:

{
  "name": "My Framework",
  "version": "v1.0",
  "description": "Optional description.",
  "controls": [
    {
      "control_id": "MF-1",
      "title": "Control Title",
      "description": "What this control requires.",
      "required_tags": ["tag-a", "tag-b"],
      "optional_tags": ["tag-c"],
      "evidence": [
        "Evidence item description 1",
        "Evidence item description 2"
      ]
    }
  ]
}

Then add the filename to FRAMEWORK_FILES in seed.py and re-run:

python seed.py    # safe to re-run — existing data is not affected

Adding Tools

Three ways to add tools:

1. Edit the catalog JSON

{
  "name": "My Tool",
  "category": "EDR",
  "description": "Endpoint detection and response.",
  "capabilities": ["endpoint-protection", "malware-detection", "EDR"]
}

Re-run python seed.py to load it.

2. UI — Tools → Add Tool

Available to admins in the web UI under the Tools section.

3. API bulk import

curl -X POST https://localhost:8443/tools/upload \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '[{"name":"My Tool","category":"EDR","capabilities":["EDR"]}]'

Project Structure

caams/
├── app/
│   ├── data/                       # Framework JSON files and tool catalog
│   ├── engine/
│   │   └── mapper.py               # Coverage computation engine
│   ├── importers/
│   │   └── cis_xlsx.py             # CIS Controls XLSX importer
│   ├── routers/
│   │   ├── api_tokens.py           # Long-lived API token management
│   │   ├── assessments.py          # Assessment CRUD, lifecycle, notes, clone
│   │   ├── audit_log.py            # Immutable audit log endpoints
│   │   ├── auditor_shares.py       # Scoped external auditor share links
│   │   ├── auth.py                 # Login, setup, user management
│   │   ├── crosswalk.py            # Framework crosswalk
│   │   ├── dashboard.py            # Org-wide executive dashboard
│   │   ├── evidence.py             # Evidence upload, approval, download
│   │   ├── export.py               # XLSX export
│   │   ├── findings.py             # Findings and risk acceptance tracker
│   │   ├── frameworks.py           # Framework and control endpoints
│   │   ├── pdf_export.py           # PDF report + evidence ZIP
│   │   ├── rfi.py                  # Request for Information endpoints
│   │   └── tools.py                # Tool catalog endpoints
│   ├── auth.py                     # JWT, password hashing, role dependencies
│   ├── database.py                 # SQLAlchemy engine + session factory
│   ├── jwt_utils.py                # Pure-Python HS256 JWT (no C deps)
│   ├── limiter.py                  # Shared rate limiter
│   ├── logging_config.py           # Rotating file handler
│   ├── main.py                     # FastAPI app, middleware, CORS, lifespan
│   ├── models.py                   # SQLAlchemy ORM models
│   └── schemas.py                  # Pydantic v2 request/response schemas
├── static/
│   ├── index.html                  # SPA shell and all view templates
│   ├── app.js                      # Alpine.js — all state and API calls
│   └── app.css                     # Inputs, buttons, cards, badges
├── caams.service                   # systemd unit file
├── install_service.sh              # Production installer
├── seed.py                         # Database seeder
├── start.sh                        # Dev start script (HTTPS)
└── requirements.txt