AGENTSECURITY.md Specification v0.1

An AGENTSECURITY.md file consists of YAML frontmatter (machine-readable metadata) and a Markdown body (human-readable policy).

Frontmatter Fields

Required Fields

Field	Type	Constraints
name	string	1-64 chars, lowercase alphanumeric + hyphens. No leading/trailing/consecutive hyphens.
description	string	1-512 chars. What the agent does and its security context.
security_tier	enum	basic | standard | strict | regulated
version	string	Spec version, major.minor format (e.g., "0.1")

Optional Fields

Field	Type	Default	Description
governance	array	[]	Compliance frameworks: NIST-AI-RMF, OWASP-LLM-TOP10, ISO-42001, EU-AI-ACT, SOC2, HIPAA, PCI-DSS, GDPR
enforcement	enum	warn	warn | block | block_and_audit
metadata	object	{}	Arbitrary key-value pairs (author, org, last_reviewed, contact)

Example

---
name: my-agent
description: "Processes support tickets and generates responses"
security_tier: standard
version: "0.1"

governance:
  - OWASP-LLM-TOP10

enforcement: warn

metadata:
  author: "dev-team"
  last_reviewed: "2026-02-22"
---

## Constraints

```yaml
constraints:
  hard_no:
    - "Never execute eval() or exec()"
    - "Never access files outside project directory"
  max_autonomous_steps: 100
```

## Tools

```yaml
tools:
  - name: file_system
    permission: read_write
    scope:
      allowed_paths: ["./src/"]
    requires_confirmation: false
```

Tier Definitions

Requirement	basic	standard	strict	regulated
Tool allowlisting	recommended	required	required	required
Human-in-the-loop	optional	high-risk	destructive ops	all external
Sandbox required	no	recommended	required	required + audited
Network restrictions	none	allowlist	strict allowlist	default-deny
Audit logging	optional	recommended	required	tamper-proof
Secret scanning	recommended	required	required	required + rotation
Compliance mapping	none	OWASP	OWASP+NIST	Full
Max steps	unlimited	100	50	25
Review cadence	none	quarterly	monthly	bi-weekly

Body Sections

The markdown body supports these recommended sections (not structurally enforced):

• Constraints — Hard rules the agent must never violate (hard_no list, max steps, escalation)
• Tools — Declared tool permissions with name, permission level, scope, and confirmation requirements
• Runtime — Sandbox type, network allowlist, resource limits, timeouts
• Human-in-the-Loop — Actions requiring approval, mechanism, timeout, escalation
• Audit — Log target, format, retention, tamper protection, alerts
• Threat Model — Primary threats and mitigations (strict+ tiers)
• Compliance Mapping — Control-to-framework mappings (regulated tier)

Validation Rules

ID	Rule	Severity	Control
ASEC-001	Missing required fields	high	Spec
ASEC-002	Invalid name format	high	Spec
ASEC-003	Invalid security_tier	high	Spec
ASEC-010	Missing tool declarations	high	LLM07
ASEC-011	Overprivileged tools	high	LLM08
ASEC-012	Missing HITL config	medium	NIST
ASEC-013	Missing sandbox	high	Agentic-5
ASEC-014	Missing audit config	high	ISO-42001
ASEC-015	Unrestricted network	high	Agentic-5
ASEC-020	Dangerous code patterns	high	LLM02
ASEC-021	Hardcoded secrets	high	LLM06
ASEC-022	Undeclared tool usage	high/med	LLM07

JSON Schema

The formal JSON Schema for frontmatter validation is available at:
spec/agentsecurity.schema.json

Full specification source: spec/AGENTSECURITY.md