cyntrisec 0.1.7__py3-none-any.whl

cyntrisec/cli/schemas.py

@@ -0,0 +1,391 @@
+"""
+Response schemas for CLI commands.
+
+These Pydantic models provide lightweight enforcement for JSON/agent
+outputs so agents can rely on a stable contract. Each command can
+reference a schema by name in emit_agent_or_json to validate data
+before it is printed.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class BaseSchema(BaseModel):
+    """Base config shared by response schemas."""
+
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+
+class ActionModel(BaseSchema):
+    command: str
+    reason: str
+
+
+class ArtifactPathsModel(BaseSchema):
+    snapshot_dir: str | None = None
+    snapshot: str | None = None
+    assets: str | None = None
+    relationships: str | None = None
+    attack_paths: str | None = None
+    findings: str | None = None
+
+
+class AgentEnvelope(BaseSchema):
+    schema_version: str
+    status: str
+    data: Any
+    message: str | None = None
+    error_code: str | None = None
+    artifact_paths: ArtifactPathsModel | None = None
+    suggested_actions: list[ActionModel] | None = None
+
+
+class ScanResponse(BaseSchema):
+    scan_id: str
+    snapshot_id: str
+    status: str
+    account_id: str | None = None
+    regions: list[str]
+    asset_count: int
+    relationship_count: int
+    finding_count: int
+    attack_path_count: int
+    warnings: list[str] | None = None
+
+
+class AttackPathOut(BaseSchema):
+    id: str
+    snapshot_id: str | None = None
+    source_asset_id: str
+    target_asset_id: str
+    path_asset_ids: list[str]
+    path_relationship_ids: list[str]
+    attack_vector: str
+    path_length: int
+    entry_confidence: float
+    exploitability_score: float
+    impact_score: float
+    risk_score: float
+    confidence_level: str | None = None
+    confidence_reason: str | None = None
+    attack_chain_relationship_ids: list[str] | None = None
+    context_relationship_ids: list[str] | None = None
+    proof: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = ConfigDict(extra="allow")
+
+
+class AnalyzePathsResponse(BaseSchema):
+    paths: list[AttackPathOut]
+    returned: int
+    total: int
+
+
+class FindingOut(BaseSchema):
+    id: str | None = None
+    snapshot_id: str | None = None
+    asset_id: str | None = None
+    finding_type: str
+    severity: str
+    title: str
+    description: str | None = None
+    remediation: str | None = None
+    evidence: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = ConfigDict(extra="allow")
+
+
+class AnalyzeFindingsResponse(BaseSchema):
+    findings: list[FindingOut]
+    total: int
+    filter: str
+
+
+class AnalyzeStatsResponse(BaseSchema):
+    snapshot_id: str | None = None
+    scan_id: str | None = None
+    account_id: str | None = None
+    asset_count: int
+    relationship_count: int
+    finding_count: int
+    path_count: int
+    regions: list[str]
+    status: str
+
+
+class WasteCandidate(BaseSchema):
+    name: str
+    asset_type: str
+    reason: str
+    asset_id: str | None = None
+    monthly_cost_usd: float | None = None
+
+
+class BusinessAsset(BaseSchema):
+    name: str
+    asset_type: str
+    reason: str
+    asset_id: str | None = None
+    tags: dict[str, str] = Field(default_factory=dict)
+
+
+class BusinessAnalysisResponse(BaseSchema):
+    entrypoints_requested: list[str]
+    entrypoints_found: list[str]
+    attackable_count: int
+    business_required_count: int
+    waste_candidate_count: int
+    waste_candidates: list[WasteCandidate]
+    business_assets: list[BusinessAsset] | None = None
+    unknown_assets: list[BusinessAsset] | None = None
+
+
+class CutRemediation(BaseSchema):
+    priority: int
+    action: str
+    description: str
+    relationship_type: str | None = None
+    source: str | None = None
+    target: str | None = None
+    paths_blocked: int
+    path_ids: list[str] = Field(default_factory=list)
+    # Cost fields
+    estimated_monthly_savings: float | None = None
+    cost_source: str | None = None
+    cost_confidence: str | None = None
+    cost_assumptions: list[str] | None = None
+
+
+class CutsResponse(BaseSchema):
+    snapshot_id: str | None = None
+    account_id: str | None = None
+    total_paths: int
+    paths_blocked: int
+    coverage: float
+    remediations: list[CutRemediation]
+
+
+class WasteCapability(BaseSchema):
+    service: str | None = None
+    service_name: str | None = None
+    days_unused: int | None = None
+    risk_level: str
+    recommendation: str
+    # Cost estimation fields
+    monthly_cost_usd_estimate: float | None = None
+    cost_source: str | None = None
+    confidence: str | None = None
+    assumptions: list[str] | None = None
+
+
+class WasteRoleReport(BaseSchema):
+    role_arn: str | None = None
+    role_name: str
+    total_services: int
+    unused_services: int
+    reduction: float
+    unused_capabilities: list[WasteCapability]
+
+
+class WasteResponse(BaseSchema):
+    snapshot_id: str | None = None
+    account_id: str | None = None
+    days_threshold: int
+    total_permissions: int
+    total_unused: int
+    blast_radius_reduction: float
+    roles: list[WasteRoleReport]
+
+
+class CanSimulation(BaseSchema):
+    action: str
+    resource: str | None = None
+    decision: str
+    matched_statements: int
+
+
+class CanResponse(BaseSchema):
+    snapshot_id: str | None = None
+    principal: str
+    resource: str
+    action: str | None = None
+    can_access: bool
+    simulations: list[CanSimulation]
+    proof: dict[str, Any] = Field(default_factory=dict)
+    mode: str | None = None
+    disclaimer: str | None = None
+
+
+class DiffChange(BaseSchema):
+    change_type: str
+    path_id: str | None = None
+    detail: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = ConfigDict(extra="allow")
+
+
+class DiffResponse(BaseSchema):
+    has_regressions: bool
+    has_improvements: bool
+    summary: dict[str, Any]
+    path_changes: list[DiffChange]
+    # Optional extra fields
+    old_snapshot: dict[str, Any] | None = None
+    new_snapshot: dict[str, Any] | None = None
+    finding_changes: list[dict[str, Any]] | None = None
+    asset_changes: list[dict[str, Any]] | None = None
+    relationship_changes: list[dict[str, Any]] | None = None
+
+    model_config = ConfigDict(extra="allow")
+
+
+class ControlResult(BaseSchema):
+    id: str
+    title: str
+    status: str
+    severity: str | None = None
+    description: str | None = None
+
+
+class DataGap(BaseSchema):
+    control_id: str
+    reason: str
+    required_assets: list[str] | None = None
+    services: list[str] | None = None
+
+
+class ComplyResponse(BaseSchema):
+    framework: str
+    compliance_score: float
+    passing: int
+    failing: int
+    controls: list[ControlResult]
+    data_gaps: list[DataGap] | None = None
+
+
+class ReportResponse(BaseSchema):
+    output_path: str
+    snapshot_id: str | None = None
+    account_id: str | None = None
+    findings: int
+    paths: int
+
+
+class ManifestResponse(BaseSchema):
+    name: str
+    version: str
+    description: str
+    capabilities: list[dict[str, Any]]
+    schemas: dict[str, Any]
+    agentic_features: dict[str, Any]
+    usage_pattern: list[str]
+
+    model_config = ConfigDict(extra="allow")
+
+
+class RemediationItem(BaseSchema):
+    priority: int
+    action: str
+    description: str
+    source: str | None = None
+    target: str | None = None
+    relationship_type: str | None = None
+    paths_blocked: int
+    terraform: str | None = None
+    status: str | None = None
+    terraform_path: str | None = None
+    terraform_result: dict[str, Any] | None = None
+
+
+class RemediateApplyResult(BaseSchema):
+    mode: str
+    output_path: str | None = None
+    terraform_path: str | None = None
+    terraform_dir: str | None = None
+    plan_exit_code: int | None = None
+    plan_summary: str | None = None
+    results: list[RemediationItem] | None = None
+
+
+class RemediateResponse(BaseSchema):
+    snapshot_id: str | None = None
+    account_id: str | None = None
+    total_paths: int
+    paths_blocked: int
+    coverage: float
+    plan: list[RemediationItem]
+    applied: bool
+    mode: str
+    output_path: str | None = None
+    terraform_path: str | None = None
+    terraform_dir: str | None = None
+    apply: RemediateApplyResult | None = None
+
+
+class AskResponse(BaseSchema):
+    query: str
+    intent: str
+    results: dict[str, Any]
+    snapshot_id: str | None = None
+    entities: dict[str, Any]
+    resolved: str
+
+
+class ExplainResponse(BaseSchema):
+    type: str
+    id: str
+    explanation: dict[str, Any]
+
+
+class SetupIamResponse(BaseSchema):
+    account_id: str
+    role_name: str
+    external_id: str | None = None
+    template_format: str
+    template: str
+    output_path: str | None = None
+
+
+class ValidateRoleResponse(BaseSchema):
+    success: bool
+    role_arn: str
+    account: str | None = None
+    arn: str | None = None
+    user_id: str | None = None
+    error: str | None = None
+    error_type: str | None = None
+
+
+class ServeToolsResponse(BaseSchema):
+    tools: list[dict[str, Any]]
+
+
+SCHEMA_REGISTRY = {
+    "scan": ScanResponse,
+    "analyze_paths": AnalyzePathsResponse,
+    "analyze_findings": AnalyzeFindingsResponse,
+    "analyze_stats": AnalyzeStatsResponse,
+    "analyze_business": BusinessAnalysisResponse,
+    "cuts": CutsResponse,
+    "waste": WasteResponse,
+    "can": CanResponse,
+    "diff": DiffResponse,
+    "comply": ComplyResponse,
+    "report": ReportResponse,
+    "manifest": ManifestResponse,
+    "remediate": RemediateResponse,
+    "ask": AskResponse,
+    "explain": ExplainResponse,
+    "setup_iam": SetupIamResponse,
+    "validate_role": ValidateRoleResponse,
+    "serve_tools": ServeToolsResponse,
+}
+
+
+def schema_json() -> dict[str, Any]:
+    """Return JSON schemas for manifest exposure."""
+    return {name: model.model_json_schema() for name, model in SCHEMA_REGISTRY.items()}

cyntrisec/cli/serve.py

@@ -0,0 +1,164 @@
+"""
+serve command - Run Cyntrisec as an MCP server for AI agents.
+
+Usage:
+    cyntrisec serve            # Start MCP server (stdio)
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+import typer
+from rich.console import Console
+
+from cyntrisec.cli.errors import EXIT_CODE_MAP, CyntriError, ErrorCode, handle_errors
+from cyntrisec.cli.output import emit_agent_or_json, resolve_format
+from cyntrisec.cli.schemas import ServeToolsResponse
+
+console = Console()
+log = logging.getLogger(__name__)
+
+
+@handle_errors
+def serve_cmd(
+    transport: str = typer.Option(
+        "stdio",
+        "--transport",
+        "-t",
+        help="Transport mode: stdio",
+    ),
+    list_tools: bool = typer.Option(
+        False,
+        "--list-tools",
+        "-l",
+        help="List available MCP tools and exit",
+    ),
+    format: str | None = typer.Option(
+        None,
+        "--format",
+        "-f",
+        help="Output format when listing tools: text, json, agent",
+    ),
+):
+    """
+    Run Cyntrisec as an MCP (Model Context Protocol) server.
+
+    This allows AI agents to invoke Cyntrisec tools directly
+    for security analysis, attack path discovery, and remediation.
+
+    Note: The server uses stdio transport and will exit if no client is connected.
+    Use with an MCP client (e.g., Claude Desktop, Cursor) that maintains the connection.
+
+    Tools exposed:
+    - list_tools: List all available tools
+    - set_session_snapshot: Set active snapshot for session
+    - get_scan_summary: Get latest scan stats
+    - get_attack_paths: List discovered attack paths
+    - get_remediations: Find optimal fixes
+    - check_access: Test "can X access Y"
+    - get_unused_permissions: Find waste
+    - check_compliance: Check CIS/SOC2
+    - compare_scans: Detect regressions
+    """
+    resolved_format = resolve_format(format, default_tty="text", allowed=["text", "json", "agent"])
+
+    if list_tools:
+        tools = _list_tools_data()
+        if resolved_format in {"json", "agent"}:
+            emit_agent_or_json(resolved_format, {"tools": tools}, schema=ServeToolsResponse)
+        else:
+            console.print_json(data={"tools": tools})
+        return
+
+    try:
+        from cyntrisec.mcp.server import HAS_MCP, run_mcp_server
+    except ImportError as e:
+        raise CyntriError(
+            error_code=ErrorCode.INTERNAL_ERROR,
+            message=f"Import error: {e}",
+            exit_code=EXIT_CODE_MAP["usage"],
+        )
+
+    if not HAS_MCP:
+        raise CyntriError(
+            error_code=ErrorCode.INVALID_QUERY,
+            message="MCP SDK not installed. Install with: pip install mcp",
+            exit_code=EXIT_CODE_MAP["usage"],
+        )
+
+    stderr_console = Console(file=sys.stderr)
+    stderr_console.print("[cyan]Starting MCP server (stdio transport)...[/cyan]")
+    stderr_console.print("[dim]AI agents can now invoke Cyntrisec tools[/dim]")
+    try:
+        run_mcp_server()
+    except Exception as e:
+        log.exception("Error in serve")
+        raise CyntriError(
+            error_code=ErrorCode.INTERNAL_ERROR,
+            message=str(e),
+            exit_code=EXIT_CODE_MAP["internal"],
+        )
+
+
+def _list_tools_data():
+    """Return available MCP tools."""
+    tools = [
+        {
+            "name": "list_tools",
+            "description": "List all available Cyntrisec tools",
+            "parameters": [],
+        },
+        {
+            "name": "set_session_snapshot",
+            "description": "Set active snapshot for session",
+            "parameters": [{"name": "snapshot_id", "type": "string", "required": False}],
+        },
+        {
+            "name": "get_scan_summary",
+            "description": "Get summary of the latest AWS scan",
+            "parameters": [],
+        },
+        {
+            "name": "get_attack_paths",
+            "description": "Get discovered attack paths with risk scores",
+            "parameters": [{"name": "max_paths", "type": "integer", "default": 10}],
+        },
+        {
+            "name": "get_remediations",
+            "description": "Find minimal set of fixes to block attack paths",
+            "parameters": [{"name": "max_cuts", "type": "integer", "default": 5}],
+        },
+        {
+            "name": "check_access",
+            "description": "Test if a principal can access a resource",
+            "parameters": [
+                {"name": "principal", "type": "string", "required": True},
+                {"name": "resource", "type": "string", "required": True},
+            ],
+        },
+        {
+            "name": "get_unused_permissions",
+            "description": "Find unused IAM permissions",
+            "parameters": [{"name": "days_threshold", "type": "integer", "default": 90}],
+        },
+        {
+            "name": "check_compliance",
+            "description": "Check CIS AWS or SOC 2 compliance",
+            "parameters": [
+                {
+                    "name": "framework",
+                    "type": "string",
+                    "enum": ["cis-aws", "soc2"],
+                    "default": "cis-aws",
+                }
+            ],
+        },
+        {
+            "name": "compare_scans",
+            "description": "Compare latest scan to previous for regressions",
+            "parameters": [],
+        },
+    ]
+    return tools