api

API

Overview

The API is a core component of the Continuous Compliance Framework. It manages all the data and aggregation for compliance, and agent-collected data.

The data structures in the service are heavily based on OSCAL (Open Security Controls Assessment Language), with the goal of full support.

Prerequisites

• Docker / Podman
• Docker Compose / Podman Compose
• Go (if running locally without Docker)

Getting Started

Using Docker Compose

This will also start the required auxiliary services.

make up
# OR podman-compose up -d
# OR docker compose up -d

curl http://localhost:8080

The command line

The API ships with a built in CLI, which can be used to run administrative tasks within.

Some examples include:

$ go run main.go run # Run the API itself

$ go run main.go bootstrap # Bootstrap JWT key files (defaults to CCF_JWT_* or private.pem/public.pem)

$ go run main.go users add # Create a new user in the CCF API which can be used to authenticate with

$ go run main.go migrate up # Create the database schema, or upgrade it to the current version

$ go run main.go oscal import -f testdata/full_ar.json # Import a single OSCAL document
$ go run main.go oscal import -f testdata/ # Import a directory with OSCAL documents

$ go run main.go help # Learn more about all the available commands

Accessing Swagger Documentation

[!IMPORTANT] Make sure you run make swag when first cloning the repository (either locally or in CI steps) otherwise the build will fail

The API exposes all of its endpoints using Swagger.

Swagger artefacts (docs.json/docs.yaml) are not stored within the repository as it is automatically generated using the swag cli tool and stored in the docs/ directory. A helper function make swag can be run anytime to generate the most up to date swagger docs.

You can access the Swagger documentation to test and interact with the API at: http://localhost:8080/swagger/index.html

Configuration

You can configure the API using environment variables or a .env file.

Available variables are shown in .env.example

JWT key behavior:

• If both CCF_JWT_PRIVATE_KEY and CCF_JWT_PUBLIC_KEY are set, run bootstraps key files at those paths (if needed) and then loads them.
• If either variable is unset, the API falls back to in-memory key generation.

Copy this file to .env to configure environment variables

cp .env.example .env

Contributing

We welcome contributions to the API!

Testing

Integration Tests

The API contains integration tests, which will run tests against a real database, ensuring the service works as expected.

The tests are marked with special build markers to avoid running them during normal development.

make test-integration

Notes

When using Podman instead of Docker, some changes are necessary for testcontainers to function correctly

# This is a workaround currently, and is currently being worked on by the testcontainers folks.
export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock
export TESTCONTAINERS_RYUK_DISABLED=true;

License

This project is licensed under the GNU AGPLv3 License - see the LICENSE file for details.