api

module

v0.1.1 Latest Latest Go to latest Published: Feb 12, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/openctemio/api

Links

Open Source Insights

README ¶

OpenCTEM API

Unified Exposure Management platform built with Clean Architecture in Go.

📚 Documentation

Guide	Description
Getting Started	Quick start guide
API Reference	Complete API endpoints
Authentication	JWT & OIDC auth flow
Permissions	Role-based access control
Architecture	System design
Configuration	Environment variables

Features

Asset Management - Track and categorize assets with criticality levels
Exposure Detection - Identify vulnerabilities and risks
Attack Path Analysis - Visualize attack vectors
Risk Scoring - Calculate and prioritize risks
Multi-source Integration - Wiz, Tenable, Snyk, CrowdStrike
Platform Agents - Shared scan infrastructure with K8s-inspired management
- Agent lifecycle management (drain, uncordon, delete)
- Bootstrap token authentication
- Lease-based heartbeat system
- Job assignment with tenant isolation

Tech Stack

Component	Technology
Language	Go 1.25+
HTTP	Standard `net/http`
Authentication	Local JWT / Keycloak OIDC
Database	PostgreSQL 17
Cache	Redis 7
Logging	Structured logging (slog)

Project Structure

openctem/
├── cmd/server/              # Application entry point
├── internal/
│   ├── domain/              # Core business logic (entities, value objects)
│   │   ├── asset/           # Asset domain
│   │   ├── agent/           # Platform agent domain
│   │   ├── admin/           # Admin user domain
│   │   ├── lease/           # Agent lease domain
│   │   └── shared/          # Shared domain types (ID, errors)
│   ├── app/                 # Application services (use cases)
│   └── infra/               # Infrastructure adapters
│       ├── http/            # HTTP server, router, handlers
│       │   ├── handlers/    # Route handlers
│       │   └── middleware/  # Auth, logging, etc.
│       └── postgres/        # PostgreSQL repositories
├── pkg/                     # Public utilities
│   ├── logger/              # Structured logging
│   ├── pagination/          # Pagination helpers
│   └── apierror/            # API error types
├── migrations/              # Database migrations
├── api/openapi/             # OpenAPI specification
├── tests/integration/       # Integration tests
└── docs/                    # Documentation

Quick Start

Prerequisites

Go 1.25+
Docker & Docker Compose
Make (optional)

Development

# Clone
git clone https://github.com/openctemio/api.git
cd api

# Setup environment
cp .env.example .env

# Start with hot reload
make docker-dev

# Or run locally
make dev

Production

# Set required environment variables
export DB_PASSWORD=your_secure_password
export REDIS_PASSWORD=your_secure_password
export AUTH_JWT_SECRET=your_64_char_secret
export CORS_ALLOWED_ORIGINS=https://your-domain.com

# Start production environment
make docker-prod

Verify

curl http://localhost:8080/health
# {"status":"healthy","timestamp":"2025-01-01T00:00:00Z"}

Docker

Docker Compose Files

File	Purpose	Usage
`docker-compose.yml`	Base configuration	Shared services (postgres, redis)
`docker-compose.dev.yml`	Development	Hot reload, debug ports
`docker-compose.prod.yml`	Production	Security hardening, no exposed DB

Development

# Start with hot reload
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# With build
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

Features:

Hot reload with Air
Delve debugger on port 2345
DB/Redis exposed for local tools
Debug logging enabled

Production

# Start production
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Security features:

DB/Redis NOT exposed externally
no-new-privileges on all containers
read_only filesystem for API
Resource limits enforced
JSON logging with rotation

Environment Variables

Required for Production:

Variable	Description
`DB_PASSWORD`	Database password
`REDIS_PASSWORD`	Redis password
`AUTH_JWT_SECRET`	JWT signing secret (min 64 chars)
`CORS_ALLOWED_ORIGINS`	Allowed CORS origins

Make Commands

make help           # Show all commands

# Development
make dev            # Run with hot reload (Air)
make run            # Run without hot reload
make test           # Run tests
make lint           # Run linter
make build          # Build binary

# Docker
make docker-dev     # Start dev environment (hot reload)
make docker-prod    # Start production environment
make docker-down    # Stop all containers
make docker-logs    # View logs

# Database
make migrate-up     # Run migrations
make migrate-down   # Rollback migration

# Security & Pre-commit
make pre-commit-install  # Install pre-commit hooks
make pre-commit-run      # Run all security checks
make security-scan       # Full security scan with OpenCTEM Agent (semgrep + gitleaks + trivy)
make gitleaks            # Run secret detection only

API Documentation

Endpoint	Description
`/docs`	Scalar API documentation UI
`/openapi.yaml`	OpenAPI 3.0 specification

Access documentation at: http://localhost:8080/docs

API Endpoints

Core API

Method	Endpoint	Description
GET	`/health`	Health check
GET	`/ready`	Readiness check
GET	`/docs`	API documentation
GET	`/openapi.yaml`	OpenAPI spec
GET	`/api/v1/assets`	List assets
POST	`/api/v1/assets`	Create asset
GET	`/api/v1/assets/{id}`	Get asset
PUT	`/api/v1/assets/{id}`	Update asset
DELETE	`/api/v1/assets/{id}`	Delete asset

Platform Admin API

Method	Endpoint	Description
GET	`/api/v1/admin/auth/validate`	Validate admin API key
GET	`/api/v1/admin/platform/stats`	Platform statistics
GET	`/api/v1/admin/agents`	List platform agents
POST	`/api/v1/admin/agents/{id}/drain`	Drain agent
POST	`/api/v1/admin/agents/{id}/uncordon`	Uncordon agent
GET	`/api/v1/admin/jobs`	List platform jobs
POST	`/api/v1/admin/jobs/{id}/cancel`	Cancel job
GET	`/api/v1/admin/tokens`	List bootstrap tokens
POST	`/api/v1/admin/tokens`	Create bootstrap token
DELETE	`/api/v1/admin/tokens/{id}`	Revoke token
GET	`/api/v1/admin/admins`	List admin users
POST	`/api/v1/admin/admins`	Create admin user
GET	`/api/v1/admin/audit-logs`	List audit logs

Platform Agent API

Method	Endpoint	Description
POST	`/api/v1/platform/agent/register`	Register new agent (bootstrap token)
POST	`/api/v1/platform/agent/lease/renew`	Renew agent lease (heartbeat)
GET	`/api/v1/platform/agent/job`	Poll for pending job (long-poll)
POST	`/api/v1/platform/agent/job/{id}/complete`	Complete job with results

Documentation

💖 Support

If you find OpenCTEM useful, please consider supporting the project:

BSC Network (BEP-20):

0x97f0891b4a682904a78e6Bc854a58819Ea972454

License

MIT License - See LICENSE file for details.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
bootstrap-admin command Package main provides a CLI tool to create the first admin user.	Package main provides a CLI tool to create the first admin user.
encrypt-credentials command Command encrypt-credentials encrypts existing plaintext credentials in the database.	Command encrypt-credentials encrypts existing plaintext credentials in the database.
openctem-admin command
openctem-admin/cmd
seed command
server command
internal
app Package app provides adapters for connecting services to sub-packages.	Package app provides adapters for connecting services to sub-packages.
app/ingest Package ingest provides unified ingestion of assets and findings from various formats.	Package ingest provides unified ingestion of assets and findings from various formats.
app/pipeline Package pipeline provides adapters to bridge app types with pipeline interfaces.	Package pipeline provides adapters to bridge app types with pipeline interfaces.
app/scan
app/validators Package validators provides template validation for different scanner types.	Package validators provides template validation for different scanner types.
config
infra/controller Package controller implements K8s-style reconciliation loop controllers for self-healing background operations.	Package controller implements K8s-style reconciliation loop controllers for self-healing background operations.
infra/fetchers Package fetchers provides template fetching from various sources (Git, S3, HTTP).	Package fetchers provides template fetching from various sources (Git, S3, HTTP).
infra/http
infra/http/handler Package handler provides HTTP handlers for the API server.	Package handler provides HTTP handlers for the API server.
infra/http/middleware Package middleware provides HTTP middleware for the API server.	Package middleware provides HTTP middleware for the API server.
infra/http/routes Package routes registers all HTTP routes for the API.	Package routes registers all HTTP routes for the API.
infra/jobs Package jobs provides background job definitions and handlers using Asynq.	Package jobs provides background job definitions and handlers using Asynq.
infra/llm Package llm provides abstractions for Large Language Model providers.	Package llm provides abstractions for Large Language Model providers.
infra/notification Package notification provides clients for sending notifications to various providers.	Package notification provides clients for sending notifications to various providers.
infra/postgres
infra/redis Package redis provides production-ready Redis integration for the OpenCTEM application.	Package redis provides production-ready Redis integration for the OpenCTEM application.
infra/scm Package scm provides client implementations for various SCM (Source Code Management) providers	Package scm provides client implementations for various SCM (Source Code Management) providers
infra/websocket Package websocket provides WebSocket infrastructure for real-time communication.	Package websocket provides WebSocket infrastructure for real-time communication.
metrics
pkg
apierror Package apierror provides standardized API error handling.	Package apierror provides standardized API error handling.
app Package app defines service interfaces for the application layer.	Package app defines service interfaces for the application layer.
crypto Package crypto provides encryption utilities for sensitive data.	Package crypto provides encryption utilities for sensitive data.
domain/accesscontrol
domain/admin Package admin defines the AdminUser domain entity for platform administration.	Package admin defines the AdminUser domain entity for platform administration.
domain/agent Package agent defines the Agent domain entity for scanner/collector/agent management.	Package agent defines the Agent domain entity for scanner/collector/agent management.
domain/aitriage Package aitriage provides domain entities for AI-powered vulnerability triage.	Package aitriage provides domain entities for AI-powered vulnerability triage.
domain/apikey
domain/asset
domain/assetgroup Package asset_group provides domain models for asset group management.	Package asset_group provides domain models for asset group management.
domain/assettype
domain/audit
domain/branch
domain/capability Package capability defines the Capability domain entity.	Package capability defines the Capability domain entity.
domain/command Package command defines the Command domain entity for server-controlled agents.	Package command defines the Command domain entity for server-controlled agents.
domain/component Package component provides the component domain model for software dependencies.	Package component provides the component domain model for software dependencies.
domain/credential Package credential provides domain types for credential leak management.	Package credential provides domain types for credential leak management.
domain/datasource
domain/exposure
domain/findingsource
domain/group
domain/integration
domain/module Package module provides domain models for tenant modules and access control.	Package module provides domain models for tenant modules and access control.
domain/notification Package notification provides domain entities for the notification system.	Package notification provides domain entities for the notification system.
domain/permission Package permission defines granular permissions for resource-based authorization.	Package permission defines granular permissions for resource-based authorization.
domain/permissionset
domain/pipeline Package pipeline defines the Pipeline domain entities for scan orchestration.	Package pipeline defines the Pipeline domain entities for scan orchestration.
domain/role Package role provides domain entities for role-based access control.	Package role provides domain entities for role-based access control.
domain/rule Package rule provides domain entities for rule management.	Package rule provides domain entities for rule management.
domain/scan Package scan defines the Scan domain entity and types.	Package scan defines the Scan domain entity and types.
domain/scannertemplate Package scanner_template defines the ScannerTemplate domain entity for custom scanner templates.	Package scanner_template defines the ScannerTemplate domain entity for custom scanner templates.
domain/scanprofile Package scanprofile defines the ScanProfile domain entity for reusable scan configurations.	Package scanprofile defines the ScanProfile domain entity for reusable scan configurations.
domain/scansession
domain/scope
domain/secretstore Package credential defines the Credential domain entity for secure credential storage.	Package credential defines the Credential domain entity for secure credential storage.
domain/session
domain/shared Package shared provides shared domain types and utilities.	Package shared provides shared domain types and utilities.
domain/sla
domain/suppression Package suppression provides domain logic for platform-controlled false positive management.	Package suppression provides domain logic for platform-controlled false positive management.
domain/templatesource Package template_source defines the TemplateSource domain entity for managing external template sources.	Package template_source defines the TemplateSource domain entity for managing external template sources.
domain/tenant
domain/threatintel Package threatintel provides the threat intelligence domain model.	Package threatintel provides the threat intelligence domain model.
domain/tool Package tool defines the Tool domain entity for the tool registry.	Package tool defines the Tool domain entity for the tool registry.
domain/toolcategory Package toolcategory defines the ToolCategory domain entity.	Package toolcategory defines the ToolCategory domain entity.
domain/user Package user provides the user domain model.	Package user provides the user domain model.
domain/vulnerability Package vulnerability provides the vulnerability domain model.	Package vulnerability provides the vulnerability domain model.
domain/webhook
domain/workflow Package workflow defines the Workflow domain entities for automation orchestration.	Package workflow defines the Workflow domain entities for automation orchestration.
email Package email provides email sending functionality using SMTP.	Package email provides email sending functionality using SMTP.
jwt Package jwt provides JWT token generation and validation utilities.	Package jwt provides JWT token generation and validation utilities.
keycloak Package keycloak provides Keycloak JWT token validation and claims extraction.	Package keycloak provides Keycloak JWT token validation and claims extraction.
logger
migrations Package migrations provides edition-aware database migration loading.	Package migrations provides edition-aware database migration loading.
pagination Package pagination provides pagination utilities.	Package pagination provides pagination utilities.
parsers/sarif Package sarif provides a comprehensive parser and utilities for SARIF (Static Analysis Results Interchange Format) version 2.1.0.	Package sarif provides a comprehensive parser and utilities for SARIF (Static Analysis Results Interchange Format) version 2.1.0.
password Package password provides secure password hashing and validation.	Package password provides secure password hashing and validation.
validator Package validator provides struct validation utilities with custom validators.	Package validator provides struct validation utilities with custom validators.