AGENTS.md

Agent Instructions

This document provides guidance for AI coding agents working on the SetupSentry codebase.

Architecture

SetupSentry is a static security scanner for repository instructions. It scans markdown files and shell scripts for dangerous patterns without executing them.

Key Components

• CLI (src/cli.ts): Entry point, argument parsing
• Scan (src/scan.ts): Orchestration, file processing
• Engine (src/engine.ts): Rule execution
• Rules (src/rules/): Individual security rules (SS001-SS010)
• Discovery (src/discovery.ts): File finding and filtering
• Markdown (src/markdown.ts): Code block extraction
• Reporters (src/reporters/): Output formatting (pretty, JSON)

Rule Interface

interface Rule {
  id: string;
  severity: Severity;
  title: string;
  description: string;
  scan(context: ScanContext): Finding[];
}

Commands

npm install        # Install dependencies
npm run build      # Compile TypeScript to dist/
npm run typecheck  # Type checking without emit
npm run lint       # Run ESLint
npm test           # Run Vitest tests
npm pack           # Package for npm publication (dry-run with --dry-run)

Test Expectations

• Every rule must have positive and negative tests
• Tests are in tests/ directory
• Run npm test to verify changes
• Tests must never execute commands found in fixtures

Rule Design Conventions

1. Each rule is in its own file: src/rules/ssXXX.ts
2. Rules are registered in src/rules/index.ts
3. Rules must be deterministic and offline
4. Prefer false negatives over false positives
5. Every finding must include: ruleId, severity, file, line, title, evidence, explanation, remediation

Important Constraints

• NEVER execute discovered commands during tests or development
• Preserve deterministic/offline behavior
• Do not add runtime dependencies unless absolutely necessary
• Use strict TypeScript (no any unless genuinely needed)
• All code is ESM (import/export, not require)

Adding a New Rule

1. Create src/rules/ssXXX.ts implementing the Rule interface
2. Add the rule to src/rules/index.ts
3. Add tests to tests/rules.test.ts
4. Update documentation in README.md

File Discovery

Files scanned:

• README*.md, AGENTS.md, CLAUDE.md, CLAUDE.local.md
• .cursorrules, .cursor/rules/**/*.md, .cursor/rules/**/*.mdc
• .github/copilot-instructions.md
• setup.sh, install.sh, scripts/setup.sh, scripts/install.sh

Excluded directories:

• node_modules, .git, dist, build, coverage, vendor