Security Agent Family Guide

Framework-Specific Security Patterns

Security agents MUST apply framework-specific checks based on the detected stack.

Server Function CSRF and Authorization

Reviewers MUST NOT report a missing handwritten Origin check in a Server Function as a CSRF finding. Next.js 16.3.4 compares the host in the request’s Origin header against the app’s own host, taken from x-forwarded-host or host, and rejects the action when the two differ. See serverActions.

Why: flagging absent code that the framework supersedes produces false positives, and a hand-rolled check that disagrees with the framework’s host comparison is a second, weaker gate to maintain.

Reviewers MUST look for two real problems instead.

First, a reverse proxy that forwards its own host rather than the public one in x-forwarded-host makes every action fail until the browser-facing host is listed. Configure it, rather than disabling the check:

// next.config.js — extra hosts allowed to invoke Server Functions
module.exports = {
  experimental: {
    serverActions: {
      allowedOrigins: ['my-proxy.com', '*.my-proxy.com'],
    },
  },
}

Second, the built-in check has a documented gap: a request carrying no Origin header at all is allowed through with a warning rather than rejected. An application with a stricter policy SHOULD reject Origin-absent state-changing requests in middleware, and MUST NOT rely on the framework check as its only authorization.

Every Server Function is a public HTTP endpoint. Rendering a form only on an authenticated page is not a security boundary, so each function MUST authenticate, MUST authorize the specific object it touches, and MUST treat FormData, parameters, and headers as untrusted. See Server Actions.

// app/items/actions.ts
'use server'

import { auth } from '@/lib/auth'
import { db } from '@/lib/db'

// Don't: no auth, no ownership check, and the whole item comes from the
// client, so anyone who can POST here can complete any item.
export async function completeItemUnsafe(item: Item) {
  await db.item.update({ where: { id: item.id }, data: { completed: true } })
}

// Do: take only the change, derive identity from the session, and look the
// row up by ownership before writing.
export async function completeItem(itemId: string) {
  const session = await auth()
  if (!session?.user) throw new Error('Unauthorized')

  const item = await db.item.findFirst({
    where: { id: itemId, ownerId: session.user.id },
  })
  if (!item) throw new Error('Forbidden')

  await db.item.update({ where: { id: item.id }, data: { completed: true } })
}

Return values are serialized to the client, so actions SHOULD return the minimum the UI renders rather than raw database records. See Data Security.

Severity Levels

All findings use RFC 2119 severity levels:

Level	Keyword	Meaning	Action Required
Critical	MUST FIX	Exploitable, data breach risk	Block merge
High	MUST	Significant security weakness	Fix before merge
Medium	SHOULD	Security improvement needed	Fix soon
Low	MAY	Minor hardening opportunity	Consider
Info	N/A	Observation only	Awareness

Install the Agents and Commands

Copy or symlink the crefft definitions into the project scope:

# Run from the root of the project you are protecting.
CREFFT=../crefft                      # path to your crefft checkout
mkdir -p .claude/agents/security .claude/commands

cp "$CREFFT"/agents/security/*.md .claude/agents/security/
cp "$CREFFT"/commands/security.md .claude/commands/
cp "$CREFFT"/commands/security-fix.md .claude/commands/
cp "$CREFFT"/commands/threat-model.md .claude/commands/
cp "$CREFFT"/commands/incident.md .claude/commands/

Teams MUST commit .claude/agents/ and .claude/commands/ so every contributor gets the same definitions. Individuals MAY install into ~/.claude/agents/ and ~/.claude/commands/ instead, which applies the family to every project on that machine.

Each agent file MUST carry name and description frontmatter. Claude Code silently skips a file missing either one and records the reason only in the debug log, so a typo produces no agent and no error:

---
name: code-security-reviewer
description: Identify code vulnerabilities with CWE/OWASP mapping. Use on
  changed source files before merge.
model: sonnet
tools: Read, Grep, Glob
---

Why: .claude/agents/ is the project location Claude Code scans for subagent definitions, and a foo.md in .claude/commands/ is what makes /foo typable. description is the only thing Claude reads when deciding whether to delegate, so it MUST say when the agent applies, not what it is.

Agent names MUST be unique across the whole tree; when two files in one agents directory declare the same name, Claude Code loads only one of them and the choice is filesystem read order. Run /doctor after installing: it reports files in the same directory that share a name.

Restrict What Each Agent May Do

Reporting agents SHOULD declare a read-only tools list in frontmatter, so an agent that is meant to find problems cannot rewrite the code it is judging. Only the Remediation Generator needs Edit.

Agent role	tools frontmatter
Reviewers, auditors, modelers, reporters	Read, Grep, Glob
Red Team Operator (needs command output)	Read, Grep, Glob, Bash
Remediation Generator	Read, Grep, Glob, Edit

Why: tools is enforced by Claude Code, not by the model, so it holds even when a prompt injection in the reviewed source tells the agent to do otherwise. Instructions in the agent body do not.

Back that with project settings that keep every agent away from credentials. Deny rules beat allow rules, and a Read deny also blocks Edit and Write on the same path:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "deny": [
      "Read(**/.env)",
      "Read(**/.env.*)",
      "Read(**/*.pem)",
      "Read(**/*.key)",
      "Read(**/id_rsa*)"
    ],
    "ask": [
      "Edit(**/.github/workflows/**)",
      "Bash(git push *)"
    ]
  }
}

Trigger Reviews on Sensitive Paths

There is no autoReview or triggerPaths setting. The supported mechanism is a PostToolUse hook whose if filter uses permission-rule path syntax. One handler is needed per path pattern, because a single if holds one rule:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "if": "Edit(**/auth/**)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/security-on-edit.sh",
            "statusMessage": "Security review of auth change"
          },
          {
            "type": "command",
            "if": "Edit(**/api/**)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/security-on-edit.sh",
            "statusMessage": "Security review of API change"
          }
        ]
      }
    ]
  }
}

Why: Edit(...) rules cover every built-in file-writing tool, including Write, whereas a Write(...) path rule is accepted and then never consulted. **/auth/** matches at any depth; a bare auth/** would match only the top-level directory in an allow rule.

The hook receives the PostToolUse JSON on stdin, not a filename argument, so it needs a small adapter over the shared security-quick.sh wrapper:

#!/usr/bin/env bash
# .claude/hooks/security-on-edit.sh — PostToolUse adapter.
set -uo pipefail

file=$(jq -r '.tool_input.file_path // empty')
[ -n "$file" ] || exit 0

wrapper="$(dirname "$0")/security-quick.sh"
if ! output=$("$wrapper" "$file" 2>&1); then
  printf '%s\n' "$output" >&2
  exit 2
fi
exit 0

The adapter MUST exit 2, not 1, when it wants Claude to act on the finding. On PostToolUse only exit 2 surfaces stderr to Claude; exit 1 is recorded as a non-blocking hook error and the turn continues, which is exactly the silent gate this section exists to avoid. PostToolUse fires after the write, so it cannot undo the edit; it tells Claude to fix what it just wrote.

type: "agent" hooks can run a subagent instead of a script, but that handler type is documented as experimental and SHOULD NOT carry a gate teams depend on.

GitHub Actions

Claude Code Action v1 takes prompt and claude_args; it has no command or fail_on input, so the severity gate MUST be a separate step that reads the structured output and exits non-zero:

# .github/workflows/security-review.yml
name: Security Review

on:
  pull_request:
    branches: [main]

permissions: {}

concurrency:
  group: security-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  security:
    # Fork pull requests cannot read secrets; skip rather than fail open.
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - name: Check out the pull request
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0

      - name: Run the security review
        id: review
        uses: anthropics/claude-code-action@9c5ddab2e6d17b83ea679153b31f1d5f023cf636 # v1.0.217
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Run /security full over the diff between
            ${{ github.event.pull_request.base.sha }} and HEAD.
            Report only findings you can tie to a changed line.
            Set highest_severity to the worst severity you report,
            or "none" when the diff is clean.
          claude_args: |
            --max-turns 12
            --json-schema '{"type":"object","required":["highest_severity"],"properties":{"highest_severity":{"type":"string","enum":["none","low","medium","high","critical"]}}}'
            --allowed-tools "Read" "Grep" "Glob" "Bash(git diff *)" "Bash(git log *)"

      - name: Enforce the severity gate
        env:
          VERDICT: ${{ steps.review.outputs.structured_output }}
          SECURITY_BLOCK_SEVERITY: high
        run: |
          set -euo pipefail
          severity=$(printf '%s' "$VERDICT" |
            jq -r '.highest_severity // empty' 2>/dev/null || true)
          if [ -z "$severity" ]; then
            echo "No structured verdict returned; failing closed." >&2
            exit 1
          fi
          rank() {
            case "$1" in
              none) echo 0 ;; low) echo 1 ;; medium) echo 2 ;;
              high) echo 3 ;; critical) echo 4 ;; *) echo 4 ;;
            esac
          }
          if [ "$(rank "$severity")" -ge "$(rank "$SECURITY_BLOCK_SEVERITY")" ]; then
            echo "Blocking: highest severity is $severity." >&2
            exit 1
          fi
          echo "Highest severity is $severity; below the gate."

Why each part is there:

• permissions: {} at workflow level drops the default token scopes, and the job grants back only contents: read and pull-requests: write, so a prompt injection in the diff cannot reach anything else.
• Actions are pinned to full commit SHAs. A tag is a mutable pointer; a SHA is the artifact you reviewed.
• --json-schema is what makes steps.review.outputs.structured_output populate. It MUST stay on one line: the action splits claude_args on whitespace.
• The gate step fails closed on an empty verdict, so a crashed or rate-limited review blocks the merge rather than passing it.
• The if guard is required because secrets.ANTHROPIC_API_KEY is empty for pull requests from forks. Reviewing untrusted forks needs pull_request_target and its own threat model; do not simply remove the guard.

Pre-commit Hook

pre-commit matches files by identify tags, and typescript is not one of them. Use types_or so the hook fires on any listed language rather than requiring a file to be all of them at once:

# .pre-commit-config.yaml
minimum_pre_commit_version: '4.6.2'
repos:
  - repo: local
    hooks:
      - id: security-quick
        name: Quick Security Scan
        entry: .claude/hooks/security-quick.sh
        language: script
        pass_filenames: true
        require_serial: true
        types_or: [python, javascript, ts, tsx]
        exclude: '^(vendor|third_party)/'

Why: types: [python, javascript, typescript] fails two ways. typescript is not a recognized tag, so pre-commit aborts with Type tag 'typescript' is not recognized; and once the spelling is corrected to ts, types is an AND across tags, so no file is both Python and JavaScript and the hook is reported as (no files to check) Skipped with exit status 0. A security hook that always passes is worse than no hook. ts and tsx are separate tags, so .tsx files need their own entry.

The entry MUST be a repository-owned script, not claude /security quick. claude "query" starts an interactive session; only claude -p runs a query and exits, and a model’s prose is not a gate until something turns it into an exit status:

#!/usr/bin/env bash
# .claude/hooks/security-quick.sh — blocks the commit on qualifying findings.
set -euo pipefail

: "${SECURITY_BLOCK_SEVERITY:=high}"
[ "$#" -gt 0 ] || exit 0

schema='{"type":"object","required":["highest_severity"],"properties":{"highest_severity":{"type":"string","enum":["none","low","medium","high","critical"]}}}'

verdict=$(printf '%s\n' "$@" | claude -p \
  'Run /security quick on the files listed on stdin. Set highest_severity
   to the worst severity you find, or "none" if the files are clean.' \
  --output-format json \
  --json-schema "$schema" \
  --permission-mode plan \
  --max-turns 6 \
  --allowed-tools "Read" "Grep" "Glob")

severity=$(printf '%s' "$verdict" |
  jq -r '.structured_output.highest_severity // empty' 2>/dev/null || true)
if [ -z "$severity" ]; then
  echo "security-quick: no structured verdict returned; failing closed." >&2
  exit 1
fi

rank() {
  case "$1" in
    none) echo 0 ;; low) echo 1 ;; medium) echo 2 ;;
    high) echo 3 ;; critical) echo 4 ;; *) echo 4 ;;
  esac
}

if [ "$(rank "$severity")" -ge "$(rank "$SECURITY_BLOCK_SEVERITY")" ]; then
  printf '%s' "$verdict" | jq -r '.result // empty' >&2 || true
  echo "security-quick: blocking commit, highest severity is $severity." >&2
  exit 1
fi

echo "security-quick: highest severity is $severity."

Both scripts MUST be executable: chmod +x .claude/hooks/security-quick.sh .claude/hooks/security-on-edit.sh. A hook whose path is wrong or not executable exits 127, which Claude Code records as a non-blocking error, so watch the first run. They need jq and a Claude Code installation that is authenticated non-interactively; claude setup-token produces a long-lived token for that. Teams SHOULD pin the Claude Code version in their bootstrap so the hook’s behavior does not drift under contributors.

DO

• MUST run /security on all PRs with code changes
• MUST run /threat-model for new features handling sensitive data
• MUST address Critical and High findings before merge
• SHOULD run /security deps weekly
• SHOULD use /compliance before audits
• MAY use /security quick for rapid iteration

DON’T

• MUST NOT ignore Critical findings
• MUST NOT skip security review for “small” changes
• SHOULD NOT rely solely on automated review (human review still needed)
• SHOULD NOT use only Code Reviewer for IaC changes

Custom Rules

Claude Code does not read a .claude/security-rules.yaml, and crefft ships no parser for one. Project-specific rules go in .claude/rules/, where every .md file is loaded and a paths frontmatter list scopes a rule so it enters context only when Claude touches matching files:

---
paths:
  - "src/**/*.{ts,tsx}"
---

# CUSTOM-001: No console.log in production code

- **MUST NOT** leave `console.log(` in shipped code; use the project logger.
- Severity: Medium. Report file and line, and propose the logger call.
- Test files (`*.test.ts`) and `debug/` are out of scope.

Why: .claude/rules/*.md is a documented location that Claude Code loads, and paths keeps a long rule set out of context until it is relevant.

Rules are context, not enforcement: they shape what an agent looks for, and they cannot stop a tool call. A rule that MUST hold regardless of the model belongs in a PreToolUse hook or a permissions.deny entry, or in a deterministic linter the pre-commit hook also runs.