AGENTS.md — ClaudeSec

Purpose

ClaudeSec is a DevSecOps toolkit for AI-assisted secure development. It provides a zero-dependency bash security scanner (see README's Scanner Categories for the per-category counts and the total), an ISMS PDCA dashboard, asset management integrations, and reusable CI/CD templates — all designed to integrate with Claude Code workflows.

npm: claudesec — version 0.7.2

Tech Stack

• Scanner: Bash (zero external dependencies), Python 3 (dashboard, compliance mapping)
• Dashboard: Python 3, HTML/JS (single-file output), nginx (Docker serve)
• CI/CD: GitHub Actions, Prowler, CodeQL, Semgrep, Trivy, Gitleaks, OSV-Scanner
• Integrations: Datadog, Google Sheets, Notion, Jamf Pro, AWS CLI, Zscaler ZIA
• Runtime: Docker, Node.js >=18 (npm package only)

Directory Structure

claudesec/
├── scanner/               # Security scanner CLI (bash entrypoint + check modules)
│   ├── claudesec          # Main CLI entrypoint
│   ├── checks/            # 11 check categories (ai, cicd, cloud, code, infra, ...)
│   ├── lib/               # Shared bash/python helpers (output, dashboard, compliance)
│   └── tests/             # Unit and integration tests (bash + pytest)
├── scripts/               # Automation: scan runners, dashboard builders, asset sync
├── hooks/                 # Claude Code pre-commit and pre-write security hooks
├── templates/             # GitHub Actions workflow templates, example configs
├── docs/                  # DevSecOps guides, compliance docs, AI security, architecture
│   ├── devsecops/         # OWASP, supply chain, cloud/K8s, pipeline, threat modeling
│   ├── ai/                # LLM Top 10, MITRE ATLAS, prompt injection, code review
│   ├── compliance/        # NIST CSF 2.0, ISO 27001/42001, KISA ISMS-P
│   ├── github/            # GitHub security features, branch protection, Actions
│   └── guides/            # Getting started, hourly ops, compliance mapping, workflows
├── assets/                # Logo, mascot, dashboard architecture SVG
├── bin/                   # npm bin entrypoint (claudesec-cli.sh)
├── nginx/                 # nginx config for dashboard serving
├── Dockerfile             # Scanner image
├── Dockerfile.nginx       # Dashboard serving image
├── docker-compose.yml     # Full stack
└── docker-compose.quickstart.yml

Quick Start

# No install
npx claudesec scan
npx claudesec dashboard

# From clone
./run                          # Full scan + dashboard + serve (localhost:11777)
./run --quick                  # Quick 3-category scan
./run --docker                 # Docker mode
npm test                       # pytest scanner/tests/

# Scanner direct
./scanner/claudesec scan
./scanner/claudesec scan --category network
./scanner/claudesec scan --format json --severity high

# Setup
./scripts/setup.sh             # Install hooks + templates
./scripts/quick-start.sh       # Docker-first quick start

Dashboard served at http://localhost:11777/.

For AI Agents

Working Instructions

• Single owner per task. Verify every change before handoff.
• Security claims must cite sources: OWASP, NIST, CIS, MITRE ATLAS.
• No PII, secrets, or company-specific IDs in the repo. Use environment variables only.
• Markdown files require YAML frontmatter with title, description, tags.
• File names: kebab-case. Code blocks must specify language.
• Timestamps: KST (UTC+9).

Agent Roles

Multi-agent workflows:

• Security guide: researcher → implementer → writer → reviewer → test-engineer
• Scanner feature: architect → implementer → test-engineer → ci-pipeline
• Hotfix: researcher → implementer → reviewer

The sec-* and ci-pipeline roles are project agents in .claude/agents/. The architect, writer, and test-engineer steps above are generic roles sourced from the global oh-my-claudecode agent catalog (there is no project-scoped .claude/agents/ file for them) — substitute your own equivalents if you are not running OMC.

Testing

npm test                                   # Full pytest suite
python3 -m pytest scanner/tests/ -v       # Verbose
bash scanner/tests/test_output_functions.sh
bash scanner/tests/test_check_cicd_pipeline.sh

• All new scanner checks require a corresponding test in scanner/tests/.
• All Markdown must pass markdownlint.
• Links validated with lychee "**/*.md".
• Dashboard tests run offline. Any test that calls generate_html_dashboard must run with CLAUDESEC_DASHBOARD_OFFLINE=1, otherwise dashboard-gen.py makes live GitHub API calls and the test can hang for minutes (root cause of the kcov 27-min stalls; see PR #190/#191). The kcov job sets it at the job level and every such test self-exports it; set the same in any new one. Enumerate them with grep -l generate_html_dashboard scanner/tests/*.sh rather than from a list here — this sentence named three and there were five, the two newest (#360, #473) having arrived after it was written.

Conventions

• Match existing bash style in scanner/lib/checks.sh for new checks.
• Use log_info, log_warn, log_fail from scanner/lib/output.sh — no raw echo in checks.
• New compliance mappings go in scanner/lib/compliance-map.py.
• CI templates live in templates/; reference composite actions in .github/actions/.

Dependencies

Key environment variables: DD_API_KEY, DD_APP_KEY, ASSET_SHEET_ID, NOTION_TOKEN, JAMF_URL, JAMF_TOKEN, OKTA_OAUTH_TOKEN, GH_TOKEN, ZSCALER_API_KEY.

See docs/guides/claude-lead-agents-and-best-practices.md for full agent best practices.