diff --git a/standards/agent-standards.md b/standards/agent-standards.md new file mode 100644 index 0000000..604a9a1 --- /dev/null +++ b/standards/agent-standards.md @@ -0,0 +1,94 @@ +# Agent Configuration Standards + +Standards for repositories that use AI agent configurations (CLAUDE.md, +AGENTS.md, BMAD modules, Claude plugins, MCP server configs). + +--- + +## Required Files + +Every repository MUST have: + +| File | Purpose | Compliance Check | +|------|---------|-----------------| +| `CLAUDE.md` | Project-level instructions for Claude Code | error if missing | +| `AGENTS.md` | Development standards for AI agents | error if missing | + +### CLAUDE.md Requirements + +- MUST reference `AGENTS.md` for development standards +- MUST NOT contain secrets, API keys, or credentials +- MUST NOT contain overly permissive tool authorization (e.g., `dangerouslySkipPermissions`) +- SHOULD define project-specific context (tech stack, conventions, key files) + +### AGENTS.md Requirements + +- MUST reference the org-level standards: `petry-projects/.github/AGENTS.md` +- MUST define project-specific development standards (testing, code style, architecture) +- MUST NOT override org-level security policies + +## Agent Configuration Security + +The workflow uses a **two-layer** approach: + +### Layer 1: AgentShield Action (deep security scan) + +The [`affaan-m/agentshield`](https://github.com/affaan-m/agentshield) GitHub +Action performs a comprehensive security scan with **102 rules** across 5 +categories: + +| Category | Rules | Coverage | +|----------|------:|----------| +| Secrets Detection | 10 rules, 14 patterns | API keys, tokens, credentials, env leaks | +| Permission Audit | 10 rules | Wildcard access, missing deny lists, dangerous flags | +| Hook Analysis | 34 rules | Command injection, data exfiltration, silent errors | +| MCP Server Security | 23 rules | High-risk servers, supply chain, hardcoded secrets | +| Agent Config Review | 25 rules | Prompt injection, auto-run, hidden instructions | + +The action produces a graded security report (A–F, 0–100 score) and fails +the build if findings at or above `high` severity are detected. + +**CLI reference (used via `npx` in CI — no install required):** + +```yaml +- name: AgentShield Security Scan + run: | + npx ecc-agentshield@1.4.0 scan \ + --path . \ + --min-severity high \ + --format terminal +``` + +### Layer 2: Org-specific structural checks + +Custom checks that enforce petry-projects conventions not covered by the +generic AgentShield scanner: + +| Rule | Severity | Description | +|------|----------|-------------| +| `required-files` | error | CLAUDE.md and AGENTS.md must exist | +| `claude-reference` | error | CLAUDE.md must reference AGENTS.md | +| `org-reference` | error | AGENTS.md must reference `petry-projects/.github/AGENTS.md` | +| `valid-frontmatter` | error | All SKILL.md files must have YAML frontmatter with `name` and `description` | + +## AgentShield CI Workflow + +Every repository MUST include `.github/workflows/agent-shield.yml`. +See [`workflows/agent-shield.yml`](workflows/agent-shield.yml) for the +standard template. + +**Standard triggers:** push to main, pull requests to main. + +The workflow runs both the AgentShield action and the org structural checks. +Either layer failing causes the build to fail. + +## Agent Ecosystem in Dependabot + +Repositories with BMAD modules or Claude plugins should track agent +dependencies. While Dependabot does not have a native "agents" ecosystem, +the AgentShield CI workflow performs equivalent version and security checks +on agent configuration files. + +For repos with `package.json` referencing BMAD modules (e.g., `bmad-method`, +`bmad-bgreat-suite`), the `npm` ecosystem already covers version tracking. +The AgentShield action adds the agent-specific security layer on top. diff --git a/standards/ci-standards.md b/standards/ci-standards.md index 67c208e..46b41db 100644 --- a/standards/ci-standards.md +++ b/standards/ci-standards.md @@ -8,10 +8,10 @@ repository must implement. ## Required Workflows -Every repository MUST have these workflows. Reusable templates for Dependabot -workflows are in [`standards/workflows/`](workflows/). The CI, CodeQL, -SonarCloud, and Claude Code workflows are documented as patterns below — copy -and adapt the examples to each repo's tech stack. +Every repository MUST have these 7 workflows. Reusable templates for Dependabot +and AgentShield workflows are in [`standards/workflows/`](workflows/). The CI, +CodeQL, SonarCloud, and Claude Code workflows are documented as patterns +below — copy and adapt the examples to each repo's tech stack. ### 1. CI Pipeline (`ci.yml`) @@ -205,6 +205,14 @@ Vulnerability scanning for all package ecosystems. See [`workflows/dependency-audit.yml`](workflows/dependency-audit.yml) and the [Dependabot Policy](dependabot-policy.md). +### 7. AgentShield (`agent-shield.yml`) + +Agent configuration security validation. Checks that CLAUDE.md and +AGENTS.md exist and follow standards, scans for secrets in agent config +files, validates SKILL.md frontmatter, and detects permission bypasses. +See [`workflows/agent-shield.yml`](workflows/agent-shield.yml) and the +[Agent Configuration Standards](agent-standards.md) for full details. + --- ## Workflow Patterns by Tech Stack @@ -454,9 +462,10 @@ autofix: 6. **Add `dependabot.yml`** from the appropriate template in [`standards/dependabot/`](dependabot/) 7. **Add `dependabot-automerge.yml`** from [`standards/workflows/`](workflows/) 8. **Add `dependency-audit.yml`** from [`standards/workflows/`](workflows/) -9. **Configure secrets** in the repository settings -10. **Set required status checks** in branch protection (see [GitHub Settings](github-settings.md)) -11. **Pin all action references** to commit SHAs +9. **Add `agent-shield.yml`** from [`standards/workflows/`](workflows/) +10. **Configure secrets** in the repository settings +11. **Set required status checks** in branch protection (see [GitHub Settings](github-settings.md)) +12. **Pin all action references** to commit SHAs --- diff --git a/standards/workflows/agent-shield.yml b/standards/workflows/agent-shield.yml new file mode 100644 index 0000000..98be81f --- /dev/null +++ b/standards/workflows/agent-shield.yml @@ -0,0 +1,103 @@ +# AgentShield — Agent configuration security validation +# See: standards/agent-standards.md +# +# Two-layer approach: +# 1. affaan-m/agentshield action — deep security scan (102 rules across +# secrets, permissions, hooks, MCP servers, and agent config) +# 2. Org-specific structural checks — required files, cross-references, +# SKILL.md frontmatter validation + +name: AgentShield + +on: + push: + branches: [main] + pull_request: + branches: [main] + +permissions: + contents: read + +jobs: + agent-shield: + name: AgentShield + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + # --- Deep security scan via AgentShield CLI --- + # Uses ecc-agentshield (https://github.com/affaan-m/agentshield) + # 102 rules: secrets, permissions, hooks, MCP servers, agent config + - name: AgentShield Security Scan + run: | + npx ecc-agentshield@1.4.0 scan \ + --path . \ + --min-severity high \ + --format terminal + + # --- Org-specific structural checks --- + - name: Check required agent files exist + run: | + status=0 + + if [ ! -f "CLAUDE.md" ]; then + echo "::error::Missing CLAUDE.md" + status=1 + fi + + if [ ! -f "AGENTS.md" ]; then + echo "::error::Missing AGENTS.md" + status=1 + fi + + exit $status + + - name: Validate cross-references + run: | + status=0 + + if [ -f "CLAUDE.md" ] && \ + ! grep -qi 'AGENTS.md' CLAUDE.md; then + echo "::error file=CLAUDE.md::Must reference AGENTS.md" + status=1 + fi + + if [ -f "AGENTS.md" ] && \ + ! grep -qi 'petry-projects/\.github' AGENTS.md; then + echo "::error file=AGENTS.md::Must reference org standards" + status=1 + fi + + exit $status + + - name: Validate SKILL.md frontmatter + run: | + status=0 + + while IFS= read -r file; do + frontmatter=$(awk \ + '/^---$/{n++; next} n==1{print} n>=2{exit}' \ + "$file") + + if [ -z "$frontmatter" ]; then + echo "::error file=$file::Missing YAML frontmatter" + status=1 + continue + fi + + if ! echo "$frontmatter" | grep -q '^name:'; then + echo "::error file=$file::Missing 'name' field" + status=1 + fi + if ! echo "$frontmatter" | grep -q '^description:'; then + echo "::error file=$file::Missing 'description' field" + status=1 + fi + done < <(find . -name 'SKILL.md' \ + -not -path '*/node_modules/*' \ + -not -path '*/.git/*') + + if [ "$status" -eq 0 ]; then + echo "All SKILL.md frontmatter validated." + fi + exit $status