Skip to content

AGENTS.md

Latest commit

 

History

History
211 lines (156 loc) · 5.86 KB

AGENTS.md

File metadata and controls

211 lines (156 loc) · 5.86 KB
Raw

AGENTS.md — Sigil

Guidance for any AI coding agent working on Sigil. Read this fully before changing anything.

If a request contradicts this document, flag the conflict instead of silently doing the bigger thing.

1. Mission

Sigil is a secrets discovery and remediation tool for developers. It scans codebases for hardcoded secrets (API keys, tokens, passwords), reports findings with source location, and optionally replaces them with references to locket — the user's encrypted vault.

Find secrets. Store them safely. Never commit them again.

2. Scope Lock (v0.1)

What v0.1 IS:

  • Go CLI that scans directories for secret patterns
  • Deterministic regex pattern matching (no ML, no entropy)
  • Source location reporting (file, line, column)
  • Severity scoring (Critical, High, Medium, Low)
  • Integration with locket via shell-out (locket add NAME --stdin)
  • Charm Bubble Tea TUI for interactive review and remediation
  • Pre-commit hook support (sigil hook install)
  • JSON report output for CI integration

What v0.1 is NOT:

  • A secrets manager (that's locket)
  • Network-based discovery (that's SepulchrynScan)
  • Detection rule authoring (that's detectsmith)
  • Web dashboard
  • ML/entropy-based detection
  • Git history scanning (only working tree)
  • Cloud provider secret scanning (AWS IAM, Azure KV, etc.)
  • Automatic rotation or revocation

3. Architecture

sigil/
├── main.go              # CLI dispatch
├── scan/
│   ├── scanner.go       # Directory walker + pattern matcher
│   ├── patterns.go      # Built-in regex patterns
│   ├── finding.go       # Finding model
│   └── scanner_test.go
├── locket/
│   ├── client.go        # Shell out to locket CLI
│   └── client_test.go
├── report/
│   ├── json.go          # JSON report writer
│   ├── markdown.go      # Markdown summary
│   └── report_test.go
├── hook/
│   ├── install.go       # Git pre-commit hook installer
│   └── hook.go          # Hook script template
├── tui/
│   ├── tui.go           # Bubble Tea TUI
│   ├── styles.go        # Lipgloss styling
│   └── screens.go       # Screen definitions
└── README.md

Max 2,000 lines including tests. Three packages max: scan, locket, tui. report and hook logic stays small and lives in their own packages.

4. CLI Surface (stable — do not expand)

sigil scan [path]          # Scan directory, print findings
sigil scan [path] --json   # Output JSON report
sigil scan [path] --fix    # Interactive: suggest locket storage
sigil hook install         # Install git pre-commit hook
sigil hook uninstall       # Remove git pre-commit hook
sigil --help
sigil --version

Do NOT add sigil add, sigil list, sigil rm, sigil edit — locket handles storage.

5. Pattern Matching

Deterministic regex only. Patterns defined in scan/patterns.go.

Pattern Example Severity
AWS Access Key ID AKIAIOSFODNN7EXAMPLE Critical
AWS Secret Key 40-char base64 Critical
GitHub PAT (classic) ghp_xxxxxxxxxxxx Critical
GitHub PAT (fine-grained) github_pat_xxx Critical
Generic API Key api_key, apikey, api-key + value High
Generic Secret secret, password, passwd, pwd + value High
Bearer Token Bearer eyJ... High
Private Key Header -----BEGIN RSA PRIVATE KEY----- Critical
Slack Token xoxb-, xoxp-, xoxa- High
OpenAI API Key sk- + 48 chars Critical

Patterns are a slice of structs. v0.2 may add custom config.

6. TUI Screens (exactly 4)

  1. Scan — path input, run scan, progress spinner
  2. Review — scrollable list of findings; r remediate, i ignore, d details
  3. Remediate — name suggestion + confirm; shells out to locket add NAME --stdin
  4. Summary — count of found/remediated/ignored; export report

No fifth screen without strong justification.

7. Locket Integration

Sigil never touches encryption. It shells out:

# Store a secret non-interactively
echo "SECRET_VALUE" | locket add NAME --stdin

If locket is not installed or --stdin is unsupported, Sigil prints the manual command for the user.

8. Pre-commit Hook

Installs to .git/hooks/pre-commit:

#!/bin/sh
sigil scan . --exit-code

Blocks only on Critical severity findings. High/Medium/Low are warned but allowed.

Hardcoded ignores:

  • test/ directories
  • *.test.* files
  • *.example files
  • *.md files

9. Tech Stack

Choice Why
Go 1.24+ Single binary, fast scanning
charmbracelet/bubbletea/v2 TUI framework
charmbracelet/lipgloss/v2 Styling
charmbracelet/bubbles/v2 List, spinner, textinput
Standard regexp Deterministic patterns
Standard path/filepath Cross-platform walking

No external scanning libraries. No git package — use os/exec for hook install.

10. UX Guidelines

  • No emojis. Box-drawing only (◆, →, ·).
  • Friendly, lowercase copy.
  • Help bar on every screen.
  • Toast messages auto-clear (3s).
  • Fixed mid-tone colors (light/dark safe).

11. Hard Rules

  • Never commit real secrets in test fixtures.
  • Never implement encryption — delegate to locket.
  • Never scan outside the given path (no .. traversal).
  • Never modify files without explicit user confirmation.
  • Respect .gitignore during scans.
  • Never add network calls. Sigil is fully offline.

12. Verification

go build ./...
go vet ./...
go test ./...

# Manual tests
sigil scan .
sigil scan . --json
sigil hook install

13. Non-Goals (v0.2+ ideas)

  • Custom pattern config file
  • Entropy-based detection
  • Git history scanning
  • Cloud provider integrations
  • Web dashboard
  • VS Code extension
  • GitHub Action