CloudSecurity AF

AI-Native Cloud Infrastructure Security Scanner Built on AgentField

Output • Why CloudSecurity • Architecture • Quick Start • Full Spec

Most IaC tools tell you everything that is wrong. CloudSecurity tells you what is most dangerous first.

It connects individual misconfigurations into realistic risk chains, validates which ones matter most, and gives teams a clear fix-first path before deployment. Open source, API-first, and designed for fast CI workflows.

One-Call DX

curl -X POST http://localhost:8080/api/v1/execute/async/cloudsecurity.scan \
  -H "Content-Type: application/json" \
  -d '{"input": {"repo_url": "https://github.com/org/infra-repo"}}'

Returns risk-prioritized attack paths — not individual findings, but chains showing how misconfigurations combine into real exploits:

{
  "attack_paths": [
    {
      "severity": "critical",
      "title": "Public S3 → IAM Escalation → RDS Exfiltration",
      "chain": [
        {"step": 1, "resource": "aws_s3_bucket.uploads", "issue": "Public read access enabled"},
        {"step": 2, "resource": "aws_iam_role.lambda_exec", "issue": "Wildcard S3 permissions + RDS access"},
        {"step": 3, "resource": "aws_db_instance.production", "issue": "No VPC restriction, accessible from Lambda"}
      ],
      "impact": "Attacker reads S3 bucket → discovers Lambda credentials → pivots to production database",
      "verdict": "confirmed",
      "remediation": "Restrict S3 ACL, scope IAM policy to specific bucket ARN, add VPC security group to RDS"
    }
  ],
  "summary": {"total_findings": 23, "attack_paths": 4, "critical": 1, "high": 2, "confirmed": 3}
}

Why CloudSecurity?

Checkov, tfsec, and KICS are strong at broad control checks. Wiz, Orca, and Prisma Cloud are strong once infrastructure is live. CloudSecurity fills the shift-left gap in between: priority-grade attack path analysis directly from IaC, before deployment.

Capability	CloudSecurity AF	Checkov / tfsec / KICS	Wiz / Orca / Prisma Cloud
Core value	Risk-prioritized attack-path triage pre-deploy	Broad policy/rule coverage	Runtime posture and exposure monitoring
Attack path chains	Yes (CHAIN phase)	No (individual findings)	Yes
Requires deployment	No — IaC only	No — IaC only	Yes — live cloud
Decision quality	Fix-first, exploitability-oriented output	Large findings list, less chain context	Strong runtime context after deploy
Remediation context	IaC fix path + impact framing	Basic fix hints	Mostly runtime-centric workflows
Cost profile	Free / open source (BYOK model cost)	Free / open source	Enterprise platform contracts ($$$)

Where CloudSecurity Sits in the Stack

CloudSecurity is not a replace-all scanner. It is the decision layer in a modern cloud security stack:

• Rule scanners (Checkov/tfsec/KICS): broad deterministic control coverage.
• CloudSecurity: pre-deploy risk prioritization and multi-resource attack-path context.
• Runtime CNAPP (Wiz/Orca/Prisma Cloud): deployed-cloud visibility and runtime monitoring.

Recommended operating model:

1. Run rule scanner + CloudSecurity in PR for breadth + fix-first prioritization.
2. Use runtime CNAPP after deploy for drift and production-state risk.

Architecture

• RECON: Reads IaC, builds a resource graph, and optionally pulls live cloud state and drift.
• HUNT: Runs 7 parallel domain hunters (IAM, network, data, secrets, compute, logging, compliance).
• CHAIN: Combines individual findings into multi-step attack paths across resources.
• PROVE: Adversarial verification — tries to disprove each path. Near-zero false positives.
• REMEDIATE: Generates IaC fix diffs and evaluates breaking change / downtime impact.

Full architecture deep-dive: docs/ARCHITECTURE.md

Quick Start

git clone https://github.com/Agent-Field/cloudsecurity-af.git && cd cloudsecurity-af
cp .env.example .env          # Add OPENROUTER_API_KEY
docker compose up --build

Starts AgentField control plane (http://localhost:8080) + CloudSecurity agent.

Trigger a scan:

curl -X POST http://localhost:8080/api/v1/execute/async/cloudsecurity.scan \
  -H "Content-Type: application/json" \
  -d '{"input": {"repo_url": "https://github.com/org/infra-repo"}}'

Poll for results:

curl http://localhost:8080/api/v1/executions/<execution_id>

REST API

CloudSecurity exposes two reasoners through the AgentField control plane. All requests go to the control plane (default http://localhost:8080), which routes execution to the agent.

Trigger a Scan

curl -X POST http://localhost:8080/api/v1/execute/async/cloudsecurity.scan \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "repo_url": "https://github.com/org/infra-repo",
      "branch": "main",
      "depth": "quick",
      "severity_threshold": "low",
      "output_formats": ["sarif", "json"]
    }
  }'

Response:

{
  "execution_id": "exec_20260312_063521_ik2ghzst",
  "run_id": "run_20260312_063521_f6zfmc7q",
  "status": "queued",
  "target": "cloudsecurity.scan",
  "created_at": "2026-03-12T06:35:21Z"
}

Check Execution Status

curl http://localhost:8080/api/v1/executions/{execution_id}

Returns queued → running → completed (or failed).

Retrieve Results

curl http://localhost:8080/api/v1/executions/{execution_id}/result

Tier 2 — Live Verification (with cloud credentials)

curl -X POST http://localhost:8080/api/v1/execute/async/cloudsecurity.prove \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "repo_url": "https://github.com/org/infra-repo",
      "cloud_provider": "aws",
      "cloud_regions": ["us-east-1"],
      "assume_role_arn": "arn:aws:iam::123456789012:role/SecurityAuditRole",
      "depth": "standard",
      "severity_threshold": "medium",
      "output_formats": ["sarif", "json"]
    }
  }'

Tier 2 runs the full HUNT → CHAIN → PROVE pipeline with read-only cloud credentials for live verification and drift detection.

Full input reference (CloudSecurityInput)

{
  "input": {
    "repo_url": "https://github.com/org/infra-repo",
    "branch": "main",
    "commit_sha": null,
    "base_commit_sha": null,
    "depth": "quick | standard | thorough",
    "severity_threshold": "critical | high | medium | low | info",
    "output_formats": ["sarif", "json", "markdown"],
    "compliance_frameworks": ["cis_aws", "soc2", "hipaa", "pci_dss"],
    "include_paths": ["modules/networking/"],
    "exclude_paths": ["tests/", ".git/"],
    "is_pr": false,
    "pr_id": null,
    "fail_on_findings": false,
    "max_cost_usd": 5.0,
    "max_duration_seconds": 3600,
    "max_concurrent_hunters": 7,
    "max_concurrent_provers": 3
  }
}

For Tier 2+ add cloud config:

{
  "input": {
    "repo_url": "...",
    "cloud_provider": "aws",
    "cloud_regions": ["us-east-1", "eu-west-1"],
    "assume_role_arn": "arn:aws:iam::123456789012:role/SecurityAuditRole"
  }
}

API endpoints summary

Method	Endpoint	Description
POST	/api/v1/execute/async/cloudsecurity.scan	Trigger Tier 1 IaC scan (async)
POST	/api/v1/execute/async/cloudsecurity.prove	Trigger Tier 2+ live verification (async)
GET	/api/v1/executions/{execution_id}	Check execution status
GET	/api/v1/executions/{execution_id}/result	Retrieve completed results
GET	/api/v1/nodes	List registered agent nodes
GET	/api/v1/health	Control plane health check

All endpoints are part of the AgentField control plane API. See the AgentField documentation for the full API reference.

Three Tiers

Tier	Input	Capability
Tier 1 (No Credentials)	repo_url	Static IaC analysis, resource graph construction, attack path discovery, and IaC remediation generation
Tier 2 (Read-Only Credentials)	repo_url + cloud config	Tier 1 plus live verification and drift detection
Tier 3 (Deep Mode)	Cloud credentials (repo optional)	Tier 2 plus full graph traversal, cross-account analysis, and deeper IAM simulation workflows

CI/CD Integration

CloudSecurity is designed for PR-time scanning with SARIF upload:

name: cloudsecurity-scan
on:
  pull_request:
    paths:
      - '**/*.tf'
      - '**/*.yaml'
      - '**/*.yml'

jobs:
  infrastructure-scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - name: Trigger CloudSecurity
        run: |
          curl -sS -X POST "$AGENTFIELD_SERVER/api/v1/execute/async/cloudsecurity.scan" \
            -H "Content-Type: application/json" \
            -d '{"input":{"repo_url":".","depth":"quick","output_formats":["sarif","json"]}}'

See docs/GITHUB_ACTIONS.md for full Tier 1 and Tier 2 workflows.

Output Formats

• sarif: SARIF 2.1.0 for GitHub code scanning and security platforms
• json: Full structured output for pipelines and APIs
• markdown: Human-readable report for platform/security reviews

Configuration

Key Environment Variables

Variable	Required	Default	Purpose
AGENTFIELD_SERVER	No	http://localhost:8080	AgentField control plane URL
NODE_ID	No	cloudsecurity	Agent node identifier
OPENROUTER_API_KEY	Yes	-	Model provider credential
CLOUDSECURITY_PROVIDER	No	opencode	Harness provider override
CLOUDSECURITY_MODEL	No	openrouter/minimax/minimax-m2.5	Harness model
CLOUDSECURITY_AI_MODEL	No	CLOUDSECURITY_MODEL/AI_MODEL fallback	.ai() gate model
CLOUDSECURITY_MAX_TURNS	No	50	Max turns per harness call
CLOUDSECURITY_REPO_PATH	No	cwd	Local repository path fallback
AGENT_CALLBACK_URL	No	http://127.0.0.1:8004	Agent callback endpoint

Core CloudSecurityInput Fields

• repo_url, branch, commit_sha, base_commit_sha
• depth (quick | standard | thorough)
• severity_threshold (critical | high | medium | low | info)
• output_formats (sarif | json | markdown)
• compliance_frameworks (for example: cis_aws, soc2, hipaa, pci_dss)
• cloud (provider, regions, account_id, assume_role_arn) for Tier 2+
• Budget controls: max_cost_usd, max_duration_seconds, max_concurrent_hunters, max_concurrent_provers
• Scope filters: include_paths, exclude_paths
• CI fields: is_pr, pr_id, fail_on_findings

Development

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

pytest
ruff check src tests
mypy src

# Build and run via Docker
docker compose build
docker compose up -d

Package metadata:

• Python: >=3.11
• License: Apache-2.0
• Core deps: agentfield, pydantic>=2.0, pyhcl2>=2.0

Open Core Model

CloudSecurity uses an open-core model: scan and prove remain open source (Apache 2.0), while enterprise adds org-scale controls such as multi-account management, scheduled monitoring, and RBAC/audit features. See docs/OPEN_CORE.md for the full tier breakdown.

License

CloudSecurity AF is licensed under Apache 2.0. See LICENSE.