Skip to content

security-controls.md

Latest commit

 

History

History
109 lines (78 loc) · 4.76 KB

security-controls.md

File metadata and controls

109 lines (78 loc) · 4.76 KB
Raw

Heddle Security Controls Reference

Quick reference for all security controls. For full threat analysis, see threat-model.md.

Implemented Controls (15 of 16)

Trust Tier Enforcement (security/trust.py)

Tier Name HTTP Methods Write Tools Cross-Agent HITL
T1 Observer GET, HEAD, OPTIONS Blocked No No
T2 Worker + POST, PUT, PATCH Allowed No No
T3 Operator + DELETE Allowed Yes No
T4 Privileged + DELETE Allowed Yes Yes

Violations are blocked (not warned) and logged to the audit trail.

Access Mode Annotations (config/schema.py, security/trust.py)

  • Every tool declares access: read or access: write (default: read)
  • T1 configs with write tools are rejected at load time (config validation)
  • T1 agents calling write tools are blocked at runtime (trust enforcement)
  • Write tools: state-modifying operations (model loading, data mutation)
  • Read tools: queries, listings, status checks — safe to call anytime
  • CLI: heddle validate checks access/tier compatibility before deployment

Credential Broker (security/credentials.py)

  • Secrets stored in ~/.heddle/secrets.json (chmod 600)
  • Per-config access policy in ~/.heddle/credential_policy.json
  • Configs use {{secret:key}} — resolved at runtime, never stored in YAML
  • Unauthorized access: denied, logged, and the tool call is aborted before any request is constructed (fail-closed)
  • CLI: heddle secrets list, set, grant, revoke, policy

Audit Logging (security/audit.py)

  • Structured JSON Lines at ~/.heddle/audit/audit.jsonl
  • SHA-256 hash-chained entries (tamper-evident)
  • Events: tool_call, http_bridge, trust_violation, credential_access, agent_lifecycle
  • Secret values redacted automatically (recursive across nested parameters; URL userinfo, query, and fragment scrubbing)
  • CLI: heddle audit show [-n N] [--event TYPE], heddle audit verify

Input Validation (security/validation.py)

  • Type checking and coercion (string, integer, number, boolean, array, object)
  • Length limits per type (string max 10,000 chars)
  • Injection pattern detection: shell, SQL, path traversal, LLM prompt injection
  • Strict mode blocks, non-strict mode passes through with logging
  • Wired into MCP server HTTP bridge dispatch pipeline

Rate Limiting (security/validation.py)

  • Sliding window counter per config per tool
  • Default: 120 requests per minute
  • Configurable per-tool RPM
  • Exceeding limit: blocked, logged as trust violation

Config Signing (security/signing.py)

  • HMAC-SHA256 signing of YAML configs
  • Auto-generated signing key at ~/.heddle/signing.key (chmod 600)
  • Tamper detection: modified configs fail verification
  • CLI: heddle sign all, heddle sign verify, heddle sign config

Config Quarantine (security/signing.py)

  • Staging directory at ~/.heddle/quarantine/
  • AI-generated configs quarantined before going live
  • Promote/reject workflow with manifest tracking
  • CLI: heddle quarantine list, promote, reject

Sandbox Policy Generation (security/sandbox.py)

  • Docker container config generation from agent YAML (policy generation, not runtime enforcement yet)
  • Resource limits scaled by trust tier (T1=256MB, T3=1GB)
  • Network policy: configs can only reach declared http_bridge hosts
  • Read-only root filesystem, scoped writable volumes
  • CLI: heddle sandbox <config>

Schema Validation (config/schema.py, config/loader.py)

  • Pydantic v2 models with strict typing
  • Cross-field validation: http_bridge refs match exposes, access modes match trust tiers
  • Config names: kebab-case. Tool names: snake_case
  • heddle validate <config> for pre-deployment checks

Escalation Rules (security/escalation.py)

  • Declarative rules in YAML that hold tool calls for review when conditions match
  • Condition types: tool name globs, numeric thresholds (param_gt), exact match (param_eq), substring (param_contains), access mode
  • Matched calls raise EscalationHold — execution stops, audit trail records the hold
  • Rules loaded from config escalation_rules field, checked in the dispatch pipeline
  • Example: smart_load with "27b" model → held (17GB+ VRAM consumption)

Remaining

Control Status Description
Network isolation (iptables) Planned Container-level network enforcement

Framework Mapping

Every control maps to at least one industry framework:

  • OWASP Agentic Security Top 10 — agentic-specific threats
  • NIST AI Risk Management Framework (AI RMF 1.0) — governance and risk
  • MAESTRO — multi-agent security layers

See the threat model Section 4 for complete cross-reference tables.