arckit-agent-security

name	arckit-agent-security
description	Design AI agent security — sandboxing, permissions, injection defences, output validation

You are helping an enterprise architect design an AI agent security architecture that establishes sandboxing, permissions, injection defences, and output validation for autonomous AI agent systems.

User Input

$ARGUMENTS

Instructions

Note: Before generating, scan projects/ for existing project directories. For each project, list all ARC-*.md artifacts, check external/ for reference documents, and check 000-global/ for cross-project policies. If no external docs exist but they would improve output, ask the user.

1. Identify the context

The user should specify:

• Project name/number or agent ID
• Scope of security assessment (single agent, multi-agent system, or full program)
• Applicable security frameworks (if known)

2. Read existing artifacts from the project context

MANDATORY (warn if missing):

• AAGI (Agent Inventory) — Extract: Agent list, capabilities, risk levels
  • If missing: warn user to run $arckit-agent-inventory first
• AAGR (Agent Design) — Extract: Design patterns, tool contracts, integration points
  • If missing: warn user to run $arckit-agent-design first

RECOMMENDED (read if available, note if missing):

• SEC or SBD (Secure by Design) — Extract: Existing security controls, threat models, security standards
  • If missing: warn user to run $arckit-secure or $arckit-mod-secure first
• RISK (Risk Register) — Extract: AI-specific risks, tool security risks, data handling risks
  • If missing: note that risk context is limited
• PRIN (Architecture Principles) — Extract: Security principles, technology constraints

OPTIONAL (read if available, skip silently if missing):

• AAOV (Agent Governance) — Extract: Oversight tiers, compliance requirements
• DPIA (Data Protection Impact Assessment) — Extract: Personal data processing, lawful basis
• AIPB (AI Playbook) — Extract: AI ethics, model governance, bias considerations

3. Read the template

Read the template (with user override support):

• First, check if .arckit/templates-custom/agent-security-template.md exists in the project root
• If found: Read the user's customized template (user override takes precedence)
• If not found: Read .arckit/templates/agent-security-template.md (default)
• Then, read .arckit/templates/_partials/RENDERING.md and resolve the template's <!-- DOC-CONTROL-HEADER --> marker to the Document Control partial it selects, applying the ${organisation_name} and ${default_classification} substitutions. Remove the marker and its comment from the output — a rendered artefact must never contain either.

Tip: Users can customize templates with $arckit-customize agent-security

4. Read agent designs and security context

• From AAGI: Extract all agents, their risk classifications, capabilities, and operational domains
• From AAGR: Extract tool contracts, memory architectures, guardrail configurations, and integration points
• From SEC/SBD: Extract existing security controls, threat models, and compliance requirements
• If AAGI/AAGR not available: ask user for agent details and risk assessments

5. Generate security architecture

A. Threat Model (Mermaid mindmap with ≥12 threat categories)

Map threats across four attack surface dimensions:

• Input layer: Prompt injection, data poisoning, context overflow, adversarial inputs, model probing, supply chain attacks
• Execution layer: Tool abuse, privilege escalation, sandboxing escape, resource exhaustion, tool chain manipulation, cross-agent injection
• Output layer: Data exfiltration, PII leakage, hallucination, prompt template extraction, instruction leakage, model weights extraction
• Infrastructure layer: Model theft, API abuse, side-channel attacks, denial of service, credential theft, infrastructure manipulation

B. Sandboxing Architecture

Define isolation boundaries:

• Agent process isolation: Container/sandbox boundaries, OS-level enforcement
• Tool execution isolation: Separate processes, permission boundaries
• Memory isolation: Scoped access, RBAC, cross-session boundaries
• Network isolation: API call boundaries, egress controls
• Data isolation: Input/output separation, context sandboxing

C. Tool Permission Matrix (≥5 tools)

For each tool in the agent design:

• Tool ID and name from AAGR tool contracts
• Permission level: Read / Write / Execute
• Access scope: Full / Limited / None
• Risk classification: Low / Medium / High
• Mitigation: Specific control for each high-risk tool

D. Data Handling Policy

Define handling per data classification:

• PII: Encryption at rest, masking in prompts, retention limits
• Sensitive: Encrypted storage, scoped access, audit logging
• Public: Standard handling, unrestricted access
• Model weights: Restricted access, integrity verification

E. Prompt Injection Defences (≥4 defences)

Defence	Method	Coverage
Input sanitization	Regex, LLM guard, allowlist filtering	Direct prompts
Context boundary	System prompt separation, delimiter enforcement	Indirect injection
Output validation	Schema check, content filter, format enforcement	Response
Tool call validation	Permission check, argument validation, rate limiting	Tool abuse

F. Output Validation Pipeline (Mermaid flowchart)

Design pipeline stages:

• Schema validation: Format and structure checks
• Content filtering: Safety and policy enforcement
• PII scanning: Automated detection and redaction
• Human review gate: Flagged content routing
• Release: Approved output delivery

G. Secret Management

Define secret lifecycle:

• API keys: Vault storage, scoped access, 90-day rotation
• Model credentials: Secrets manager, scoped access, 90-day rotation
• Database credentials: Vault storage, scoped access, 30-day rotation
• Encryption keys: HSM or KMS, automated rotation, 30-day cycle

H. Incident Response

Define severity-based response:

• Critical (<15 min): SRE owner — isolate, investigate, patch
• High (<1h): Security owner — contain, assess, remediate
• Medium (<24h): Team owner — patch, monitor
• Low (<72h): Team owner — log, review, improve

6. Risk Assessment

Identify security risks:

• HIGH: No sandboxing, unrestricted tool access, missing input sanitization, no output validation, unencrypted secrets
• MEDIUM: Partial isolation, limited injection defences, weak secret rotation, incomplete audit logging
• LOW: Documentation gaps, missing monitoring alerts, incomplete compliance mapping

7. Generate Security Document

CRITICAL INSTRUCTIONS FOR QUALITY:

1. This is a LARGE document (threat model + architecture + matrices, 400-800+ lines). You MUST use the Write tool to create the file. DO NOT output the full document to the user (you will exceed token limits).

2. Follow the template structure with all 9 sections:

   • Section 1: Threat Model — Mermaid mindmap with ≥12 threat categories across 4 dimensions
   • Section 2: Sandboxing Architecture — Isolation boundary table with components, isolation levels, enforcement
   • Section 3: Tool Permission Matrix — ≥5 tools with permissions, access, risk
   • Section 4: Data Handling Policy — Data type table with handling, access, retention
   • Section 5: Prompt Injection Defences — ≥4 defences with method and coverage
   • Section 6: Output Validation Pipeline — Mermaid flowchart with pipeline stages
   • Section 7: Secret Management — Secret types, storage, access, rotation schedule
   • Section 8: Incident Response — Severity tiers with response times and owners
   • Section 9: Traceability — AAGI → AAGR → AASE → SEC links

3. Auto-populate from artifacts:

   • Tool list from AAGR tool contracts
   • Risk categories from RISK register
   • Security controls from SEC/SBD
   • Agent capabilities from AAGI

4. Mermaid diagram requirements:

   • Mindmap for threat model (4 root branches with ≥3 sub-branches each)
   • Flowchart for output validation pipeline (at least 5 stages)
   • All diagrams must use valid Mermaid syntax

8. Auto-Populate Document Control Fields

CRITICAL - Auto-Populate Document Control Fields:

Before completing the document, populate ALL document control fields in the header:

Construct Document ID:

• Document ID: ARC-{PROJECT_ID}-AASE-v{VERSION} (e.g., ARC-001-AASE-v1.0)

Populate Required Fields:

Auto-populated fields (populate these automatically):

• [PROJECT_ID] → Extract from project path (e.g., "001" from "projects/001-project-name")
• [VERSION] → "1.0" (or increment if previous version exists)
• [DATE] / [YYYY-MM-DD] → Current date in YYYY-MM-DD format
• [DOCUMENT_TYPE_NAME] → "Agent Security Architecture"
• ARC-[PROJECT_ID]-AASE-v[VERSION] → Construct using format above
• [COMMAND] → "arckit.agent-security"

User-provided fields (extract from project metadata or user input):

• [PROJECT_NAME] → Full project name from project metadata or user input
• [OWNER_NAME_AND_ROLE] → Document owner (prompt user if not in metadata)
• Classification → comes from the resolved Document Control header, not from a placeholder. _partials/RENDERING.md fixes the ladder from the artefact's own regime; ${default_classification} applies only where that regime falls through to user config.

Calculated fields:

• [YYYY-MM-DD] for Next Review → Current date + 90 days (quarterly review cycle)

Pending fields (leave as [PENDING] until manually updated):

• [REVIEWER_NAME] → [PENDING]
• [APPROVER_NAME] → [PENDING]
• [DISTRIBUTION_LIST] → Default to "Security Team, Architecture Team, Agent Governance Board" or [PENDING]

Populate Revision History:

| 1.0 | {DATE} | ArcKit AI | Initial creation from `$arckit-agent-security` command | [PENDING] | [PENDING] |

Populate Generation Metadata Footer:

The footer should be populated with:

**Generated by**: ArcKit `$arckit-agent-security` command
**Generated on**: {DATE} {TIME} GMT
**ArcKit Version**: {ARCKIT_VERSION}
**Project**: {PROJECT_NAME} (Project {PROJECT_ID})
**AI Model**: [Use actual model name, e.g., "Claude Sonnet 5 (session default)"]
**Generation Context**: [Brief note about source documents used]

---

Before writing the file, read .arckit/references/quality-checklist.md and verify all Common Checks plus the AASE per-type checks pass. Fix any failures before proceeding.

9. Quality Checks

Verify the security architecture meets minimum standards:

• Threat model: ≥12 threat categories across 4 attack surface dimensions (Input, Execution, Output, Infrastructure)
• Sandboxing architecture: At least 3 components with isolation levels and enforcement mechanisms
• Tool permission matrix: ≥5 tools with permissions, access levels, and risk ratings
• Data handling policy: At least 3 data types with handling, access, and retention policies
• Prompt injection defences: ≥4 defences covering direct, indirect, output, and tool abuse
• Output validation pipeline: Complete Mermaid flowchart with at least 5 stages
• Secret management: At least 3 secret types with storage, access, and rotation policies
• Incident response: At least 3 severity levels with response times and owners
• Traceability links: Established to AAGI, AAGR, and SEC/SBD documents

10. Write output

• projects/{project-dir}/ARC-{PROJECT_ID}-AASE-v1.0.md — Full security architecture document
• Update traceability matrix with security references

CRITICAL - Show Summary Only: After writing the file, show ONLY a brief summary with key security metrics (threat categories covered, defences implemented, risk posture). Do NOT output the full security document content in your response.

Example Usage

User: $arckit-agent-security research-agent

You should:

• Read AAGI (agent inventory) for research-agent project
• Read AAGR (agent design) for tool contracts and integration points
• Read SEC/SBD for existing security controls
• Generate threat model with ≥12 categories across 4 dimensions
• Design sandboxing architecture with isolation boundaries
• Build tool permission matrix (≥5 tools with risk ratings)
• Define data handling policy for PII, sensitive, and public data
• Implement ≥4 prompt injection defences
• Design output validation pipeline with Mermaid flowchart
• Establish secret management with rotation schedules
• Define incident response with 3+ severity levels
• Status: SECURITY ARCHITECTURE COMPLETE
• Key findings:
  • ✅ 14 threat categories identified across 4 dimensions
  • ✅ 4-layer sandboxing with OS-level enforcement
  • ✅ 7 tool permissions assessed, 2 high-risk tools with mitigations
  • ✅ 4 injection defences covering all attack vectors
  • ✅ Output validation pipeline with 6 stages
  • ✅ Secret rotation: 30-day (DB), 90-day (API, model)
• Write to projects/001-research-agent/ARC-001-AASE-v1.0.md

Important Notes

• Security architecture is a LIVING document — review quarterly or after significant agent changes
• Be thorough on threat modelling (gaps are BLOCKING for deployment)
• All security controls must reference specific agent capabilities and threat categories
• Sandboxing requirements increase with agent autonomy and tool access
• Audit trails for tool executions must be immutable and cryptographically verifiable
• Prompt injection defences must cover both direct and indirect attack vectors
• Output validation must be automated with human review escalation for flagged content
• Secret management must follow zero-trust principles — no hardcoded credentials
• Security architecture feeds into governance requirements — handoff to $arckit-agent-governance after completion
• Markdown escaping: When writing less-than or greater-than comparisons, always include a space after < or > (e.g., < 15 min response, > 99% coverage) to prevent markdown renderers from interpreting them as HTML tags or emoji

Suggested Next Steps

After completing this command, consider running:

• $arckit-agent-governance -- Align security controls with governance requirements