Automated security assessment platform that replaces manual tool-by-tool scanning with a single API call. Point it at a target — the AI planner selects the right tools, runs them in parallel, scores risks with CVSS-like precision, maps findings to compliance frameworks (OWASP Top 10, CIS Controls), and delivers a professional HTML report.
Note: For authorized security testing only. Always obtain written permission before scanning any target.
- One command, full assessment — Submit a target and get a complete security report. No manual tool selection or configuration required
- Intelligent planning — AI analyzes the target type (domain, IP, subnet, URL) and builds an optimal scan plan with dependency ordering
- Adaptive escalation — If port scanning discovers web services, vulnerability scanning triggers automatically
- Parallel execution — Independent tools run concurrently, cutting assessment time significantly
- Risk scoring — CVSS-like formula enhanced with AI contextual analysis for accurate prioritization
- Compliance mapping — Every finding automatically mapped to OWASP Top 10 2021 and CIS Controls v8
- Professional reports — Executive summaries, detailed findings, remediation guidance, and compliance tables in a single HTML document
- Docker isolation — Each security tool runs in its own container for safety and reproducibility
The system generates professional HTML reports. Here's a fragment of the findings section:
┌──────────────────────────────────────────────────────────────┐
│ SECURITY ASSESSMENT REPORT — example.com │
│ Date: 2026-03-05 │ Risk Score: 8.7 / 10 (HIGH) │
├──────────────────────────────────────────────────────────────┤
│ │
│ EXECUTIVE SUMMARY │
│ Identified 14 findings across 4 tools. │
│ 1 critical, 3 high, 5 medium, 2 low, 3 informational. │
│ Immediate action required for CVE-2021-44228 (Log4j RCE). │
│ │
│ CRITICAL FINDINGS │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ ● CVE-2021-44228 — Log4j Remote Code Execution │ │
│ │ Severity: CRITICAL │ CVSS: 9.8 │ │
│ │ Target: example.com:443 │ │
│ │ Remediation: Upgrade to Log4j 2.17+ │ │
│ │ Compliance: OWASP A06, CIS-2, CIS-7 │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ ● Missing X-Frame-Options Header │ │
│ │ Severity: MEDIUM │ Category: Misconfiguration │ │
│ │ Compliance: OWASP A05, CIS-4 │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ COMPLIANCE MAPPING │
│ OWASP Top 10 2021: A01 ✗ A02 ✗ A03 ✗ A04 ✗ A05 ● │
│ A06 ● A07 ✗ A08 ✗ A09 ✗ A10 ✗ │
│ CIS Controls v8: CIS-2 ● CIS-4 ● CIS-7 ● │
└──────────────────────────────────────────────────────────────┘
graph TB
Client[Client / API] --> API[FastAPI Gateway]
API --> Planner[AI Assessment Planner]
Planner --> LLM[LLM Provider]
Planner --> Orchestrator[Tool Orchestrator]
Orchestrator --> MCP_Nmap[MCP: Nmap] --> Docker_Nmap[Docker: nmap]
Orchestrator --> MCP_Nuclei[MCP: Nuclei] --> Docker_Nuclei[Docker: nuclei]
Orchestrator --> MCP_OSINT[MCP: OSINT Tools]
Orchestrator --> Aggregator[Results Aggregator]
Aggregator --> RiskScorer[AI Risk Scorer]
Aggregator --> Compliance[Compliance Mapper]
RiskScorer --> Reporter[Report Generator]
Compliance --> Reporter
Reporter --> API
git clone https://github.com/ForwardCodeSolutions/ai-security-orchestrator.git
cd ai-security-orchestrator
cp .env.example .env # Configure API_KEY and OPENAI_API_KEY
make dev # docker compose up -d + uvicornAPI available at http://localhost:8002/docs (interactive OpenAPI documentation).
- Docker Desktop — required for nmap and nuclei containers
- uv — Python package manager (
curl -LsSf https://astral.sh/uv/install.sh | sh) - OpenAI API key — for AI planner and report generation (get one here)
- Clone and configure:
git clone https://github.com/ForwardCodeSolutions/ai-security-orchestrator.git
cd ai-security-orchestrator
cp .env.example .env- Edit
.env:
API_KEY=your-secret-key # any string you choose
OPENAI_API_KEY=sk-... # from platform.openai.com
- Start all services:
make dev- Open interactive API docs: http://localhost:8002/docs
Use scanme.nmap.org — an official test server provided by the nmap project, authorized for scanning:
curl -X POST http://localhost:8002/api/v1/assessments \
-H "Content-Type: application/json" \
-H "X-API-Key: your-secret-key" \
-d '{"target": "scanme.nmap.org"}'
⚠️ Only scan targets you own or have explicit written permission to test.
curl -X POST http://localhost:8002/api/v1/assessments \
-H "Content-Type: application/json" \
-H "X-API-Key: your-secret-key" \
-d '{"target": "example.com"}'{
"id": "550e8400-e29b-41d4-a716-446655440000",
"target": "example.com",
"status": "planned",
"message": "Assessment planned for example.com"
}# Poll status
curl http://localhost:8002/api/v1/assessments/{id} \
-H "X-API-Key: your-secret-key"
# Get HTML report (when status = completed)
curl http://localhost:8002/api/v1/assessments/{id}/report \
-H "X-API-Key: your-secret-key"curl -X POST http://localhost:8002/api/v1/tools/nmap/run \
-H "Content-Type: application/json" \
-H "X-API-Key: your-secret-key" \
-d '{"target": "192.168.1.1", "options": {"scan_type": "quick"}}'import httpx
API = "http://localhost:8002/api/v1"
HEADERS = {"X-API-Key": "your-secret-key"}
# 1. Create assessment — AI selects tools automatically
resp = httpx.post(f"{API}/assessments", json={"target": "example.com"}, headers=HEADERS)
assessment_id = resp.json()["id"]
# 2. Poll until completed
status = httpx.get(f"{API}/assessments/{assessment_id}", headers=HEADERS).json()
# 3. Get the HTML report
report = httpx.get(f"{API}/assessments/{assessment_id}/report", headers=HEADERS).json()Full API documentation: docs/api.md
| Tool | Description | Isolation |
|---|---|---|
| nmap | Network port scanner and service detection | Docker container |
| nuclei | Vulnerability scanner with 8000+ community templates | Docker container |
| OSINT | Whois, DNS enumeration, subdomain discovery, HTTP headers | Python-native |
| SSL | SSL/TLS certificate and configuration analysis | Python-native |
| Framework | Coverage |
|---|---|
| OWASP Top 10 2021 | A01–A10 with keyword-based refinement (injection, SSRF, IDOR, etc.) |
| CIS Controls v8 | CIS-1 through CIS-16 mapped by finding category |
Add a new security tool in three steps:
- Create an MCP server in
src/security_orchestrator/mcp/your_tool_server.py:
from security_orchestrator.mcp.base_mcp import BaseMCPServer
from security_orchestrator.models.tool import ToolConfig, ToolResult
from security_orchestrator.models.finding import Finding
class YourToolMCPServer(BaseMCPServer):
def __init__(self, config: ToolConfig | None = None) -> None:
super().__init__(config or ToolConfig(
name="your_tool",
description="What it does",
docker_image="your/image:latest",
))
async def run_tool(self, target: str, params: dict | None = None) -> ToolResult:
# Execute tool and return structured results
...
def parse_findings(self, tool_result: ToolResult, assessment_id: str) -> list[Finding]:
# Parse raw output into Finding objects
...- Register in
api/dependencies.py - Add tests in
tests/unit/test_your_tool_mcp.py
Architecture decisions are documented as ADRs in docs/decisions/:
- ADR-001 — AI orchestration over static scripts
- ADR-002 — MCP protocol for tool integration
- ADR-003 — Docker isolation for security tools
- ADR-004 — AI-powered report generation
- ADR-005 — AI-driven risk scoring
| Metric | Value |
|---|---|
| Test suite | 284 tests (unit + integration) |
| Linting | ruff (check + format), zero warnings |
| Type safety | Full type hints on all functions and methods |
| Async | Non-blocking I/O throughout (FastAPI + asyncio) |
| Logging | Structured logging via structlog |
- Python 3.11+ — full type hints, modern syntax
- FastAPI — async REST API with OpenAPI docs
- Pydantic v2 — data validation and settings
- Docker — tool isolation and reproducible environments
- Jinja2 — report templates
- httpx — async HTTP client
- dnspython — DNS resolution
- structlog — structured logging
- uv — fast Python package manager
- ruff — linting and formatting
- pytest + pytest-asyncio — testing framework
make dev # Start all services
make test # Run test suite (284 tests)
make lint # Run linter
make check # Lint + test
make fix # Auto-fix lint issuesMIT