Skip to content

security_controls.md

Latest commit

 

History

History
99 lines (74 loc) · 6.63 KB

security_controls.md

File metadata and controls

99 lines (74 loc) · 6.63 KB
Raw

Security Control Model (SCM) & Approval Workflow

This document details the technical implementation and operational usage of the Security Control Model (SCM), the core protection layer of the Pentesting MCP Server.

1. Overview

The SCM acts as a centralized validation gate for every tool invocation. No tool execution proceeds without passing through the validate_request() method, which enforces:

  • Session Validity: Ensuring the engagement session is active and not expired.
  • Scope Compliance: Verifying that targets (IPs/Domains) are within the authorized engagement bounds.
  • Policy Enforcement: Checking if the tool's risk profile is allowed in the current environment.
  • Approval Requirements: Managing the Human-in-the-Loop (HITL) workflow for high-risk actions.

1.1 Unified Tool Manifest (core/tool_manifest.py)

To prevent configuration drift and divergence across execution pipelines (FastMCP stdio standalone vs. Agent Bridge), all tools are declared in a centralized Unified Tool Manifest. This manifest defines:

  • The execution context (native for host Windows execution vs. docker for container sandbox execution).
  • Active pipeline enablement (pipelines: ["mcp", "agent"]), allowing granular cherry-picking of tools depending on the environment.

2. Risk Profiles

Every tool in the system is assigned a Risk Profile that determines the level of scrutiny required:

Profile Description Typical Actions Control Requirements
READ Passive lookup, no target contact. whois, dns_lookup, cve_search Session Only
PROBE Non-intrusive target contact. ping, port_scan, cert_check Session + Scope
SCAN Active interaction, may be noisy. vuln_scan, directory_bruteforce Session + Scope + Policy
EXPLOIT Active payload delivery. sql_injection, metasploit_run Session + Scope + Policy + Approval
CRITICAL Irreversible or destructive. log_clearing, data_exfil Session + Scope + Policy + Double Approval

3. Execution Levels (L0 - L3)

The system supports four distinct execution levels. The SCM enforcement behavior changes based on the requested level:

  • L0 (VALIDATE): Syntax and scope check only. No tool execution.
  • L1 (SIMULATE): Mock execution using synthetic data. Useful for agent testing.
  • L2 (PROBE): Real execution but with non-intrusive flags (e.g., -sS in Nmap).
  • L3 (EXECUTE): Full execution. This level triggers the mandatory approval flow for EXPLOIT and CRITICAL profiles.

4. Approval Workflow

When an agent needs to execute an L3 action with an EXPLOIT profile, it must follow this lifecycle:

  1. Request: The agent calls approval_request(method, params, profile, justification).
  2. Evaluation:
    • If the target is in an Auto-Approval Scope, the request is immediately approved by the system.
    • Otherwise, it remains pending_approval.
  3. Notification: The system emits an AGENT_APPROVAL_REQUIRED event (and logs to console).
  4. Decision: A human operator (Team Lead) reviews the request via the UI or CLI and grants/denies approval.
  5. Execution: The agent polls approval_status(request_id). Once approved, it calls the tool passing the request_id.

4.1 Auto-Approval (Conditional Bypass)

To optimize workflows in lab or staging environments, you can define Auto-Approval Targets in the EngagementScope. Actions targeting these ranges skip the manual approval step while still being logged and audited.

Configuration Example (config.yaml or session_create):

{
  "scope": {
    "ip_ranges": ["10.0.0.0/8", "192.168.1.0/24"],
    "domains": ["*.lab.internal"]
  },
  "auto_approval_targets": ["127.0.0.1", "10.0.0.0/24"]
}

4.2 Permissive Extraction & Supervised Execution (CodeBlockExtractor)

To allow operators to configure how Markdown command blocks (e.g., ```bash) generated by the LLM are handled, the system implements a configurable CodeBlockExtractor with three distinct operational modes:

  • none: Command blocks in text are ignored; commands must be called explicitly via the kali_exec tool.
  • auto: Command blocks are automatically extracted and executed as kali_exec calls under the standard SCM policy (fully autonomous in auto-approved scopes).
  • supervised: Extracted command blocks are automatically tagged with _extracted_supervised: True. The SCM intercepts this tag (Layer 4) and unconditionally forces manual HITL approval (requires_approval = True, auto_approved = False), regardless of whether the target IP is in the auto-approval list.

4.3 Async Tool Lifecycle & Non-Blocking Heartbeats

Certain heavy operations (like live_packet_analysis or scans) run in async_mode to prevent blocking the agent's reasoning loop.

  • Non-blocking Execution: When a background job is started, the SCM returns a starter confirmation. The agent is prompted with a system guidance message enabling it to execute other reasoning turns or reply WAIT_FOR_JOBS to yield CPU cycles.
  • Lightweight Heartbeat: Every 60 seconds (configurable), the idle heartbeat loop (bridge/main.py) performs a lightweight, targeted state evaluation of active/pending jobs, recent history, and logs instead of a full, expensive ReAct reasoning cycle.

5. Audit Trail Integration

Every step of the security lifecycle is recorded in the Audit Trail:

  • The initial ExecutionRequest creation.
  • The approval decision (and who made it).
  • The actual tool execution parameters.
  • The outcome and data hash.

This ensures that even auto-approved actions are fully traceable and non-repudiable.

6. Network Exposure and Connectivity

6.1 Bridge Binding (0.0.0.0)

To ensure that Docker containers (especially those not in host network mode) and remote consoles can reach the API Bridge, the system is configured to listen on 0.0.0.0.

Warning

Binding to 0.0.0.0 exposes the API Bridge to your entire local network. Since the bridge currently lacks native authentication, any device on the network could theoretically trigger tool executions or approve requests if they know the bridge's IP and port.

6.2 Connectivity Guardrails

  • Firewall: It is strongly recommended to use a host-based firewall (like ufw or Windows Firewall) to restrict access to port 8321 only from the Docker bridge network and authorized operator IPs.
  • VPN: In production or sensitive environments, the bridge should only be accessible over a secure VPN.
  • CORS: The bridge implements a wildcard CORS policy ("*") in lab mode to facilitate remote UI access, which should be restricted in more sensitive deployments.