ClaudeSec

AI Security Best Practices toolkit for secure development with Claude Code

ClaudeSec integrates security best practices directly into your AI-powered development workflow. It provides security-focused prompts, hooks, templates, and guides designed for use with Claude Code and CI/CD pipelines.

Quick Start

npx (no install)

npx claudesec scan                # Security scan — no install needed
npx claudesec dashboard           # Full scan + dashboard

Git clone + Docker

git clone https://github.com/Twodragon0/claudesec.git
cd claudesec
./scripts/quick-start.sh          # Docker build + scan + serve

Claude Code slash commands

/scan                             # Run security scan
/dashboard                        # Build + serve dashboard
/audit                            # Full security audit
/team-scan                        # Parallel multi-agent scan
/security-review                  # Pre-commit security check

Dashboard serves at http://localhost:11777/

Options

npx claudesec scan                      # Scan only
npx claudesec dashboard                 # Full scan + dashboard
./scripts/quick-start.sh --scan-only    # Docker scan only
./scripts/quick-start.sh --serve        # Serve existing dashboard

Asset Management Dashboard (optional — requires API keys)

cp .env.example ~/Desktop/.env          # Edit with your API keys
./scripts/setup.sh                      # Install hooks + templates
source .venv-asset/bin/activate
python3 scripts/build-dashboard.py      # Build asset dashboard
docker compose up dashboard -d          # Serve on localhost:11777

Requires: Docker Desktop. See .env.example for API key setup.

Or run the script directly:

./scripts/run-full-dashboard.sh              # full + serve
./scripts/run-full-dashboard.sh --no-serve   # full, no server
./scripts/run-full-dashboard.sh --quick      # quick + serve
./scripts/run-dashboard-safe.sh              # full + serve (auto fallback port when 11777 is busy)
./scripts/run-dashboard-safe.sh --kill-port  # full + serve (terminate process occupying 11777)
./scripts/run-dashboard-safe.sh --docker     # run dashboard workflow in Docker

Docker Run

The default image runs local scanner categories (code, access-control, infra, cicd, saas, etc.) and now includes kubectl + prowler CLI so -c prowler / Kubernetes scans can also run inside Docker (assuming you mount credentials/kubeconfig). For production-grade cloud/K8s scanning, prefer running on the host with --kubeconfig and AWS/GCP/Azure SSO profiles, or use a hardened custom image that adds your org-specific tooling.

# Build image once (or let wrappers auto-build)
docker build -t claudesec:local .

# Dashboard flow in Docker
./run --docker
./run --docker --no-serve
./run --docker --quick

# Scanner flow in Docker
./scripts/run-scan-docker.sh
./scripts/run-scan-docker.sh -c code
./scripts/run-scan-docker.sh -c infra
./scripts/run-scan-docker.sh -c access-control

Recommended day-to-day flow:

./scripts/run-dashboard-safe.sh --kill-port  # avoid port-conflict / stale-server issues
./run --quick                                # fast smoke check
./run --no-serve                             # final full scan artifact generation
grep -q "ClaudeSec local security scanner results" claudesec-dashboard.html

Not sure where to start?

From the repo root, run ./run. The first run may take a few minutes (full scan); use ./run --quick for a faster try with 3 categories. For container-first validation, run ./run --docker --no-serve and check claudesec-dashboard.html.

Why ClaudeSec?

AI coding assistants accelerate development — but speed without security creates risk. ClaudeSec bridges this gap:

• Shift-left security: Catch vulnerabilities before they reach production
• AI-native guardrails: Security hooks and prompts designed for Claude Code workflows
• AI Security automation: GitHub Actions, pre-commit hooks, and CI/CD templates
• SaaS security scanning: Datadog, Cloudflare, Vercel, ArgoCD, Sentry, Okta, SendGrid, and more
• Supply chain integrity: SLSA, SBOM, and artifact signing workflows
• Compliance mapping: SOC 2, ISO 27001, NIST, PCI-DSS, KISA ISMS-P, KISA 주요정보통신기반시설
• Living documentation: Actionable guides for OWASP Top 10, MITRE ATLAS, and more

ISMS Asset & Security Dashboard

ClaudeSec provides an ISMS PDCA-based integrated dashboard that combines security scanning, asset management, and vulnerability assessment into a single view.

One Command — Full Asset Scan + Dashboard

# Full: security scan + asset collection + dashboard build + Docker serve
./run-all.sh

# Quick scan only (code, infra, cicd)
./run-all.sh --quick

# Include AWS infrastructure collection
./run-all.sh --aws

# Build dashboard only (skip scan)
./run-all.sh --build-only

Dashboard served at http://localhost:11777 (Docker) with 9 tabs:

Data Collection

The dashboard aggregates data from multiple sources:

Data Sources                  Collection Method
─────────────────────────────────────────────────
Datadog API                   Hosts, SIEM signals, SentinelOne logs
Google Sheets API             Asset registry, SaaS, licenses
Google Drive API (xlsx)       SaaS cost/spending data
AWS CLI (describe)            EC2, RDS, ElastiCache, S3, EKS
Prowler (K8s Job)             CIS benchmark, security checks
Notion API                    Security audit history
ClaudeSec Scanner             Code, infra, CI/CD, AI checks

Cross-Verification

Automatically detects discrepancies between data sources:

• EC2 cross-verify: AWS live instances vs asset registry (Karpenter dynamic nodes auto-excluded)
• Endpoint cross-verify: Jamf MDM vs SentinelOne EDR (identifies devices missing protection)
• SaaS auth audit: Identifies ID/PW-only services that need SSO migration

Configuration

# Required: Google OAuth (first-time browser auth)
pip install gspread google-auth google-auth-oauthlib openpyxl

# Required: Datadog API keys in ~/Desktop/.env
# datadog_key_credential=<API_KEY>
# datadog_app_key_credential=<APP_KEY>

# Optional: AWS profiles for infrastructure collection
# Requires valid AWS CLI sessions (SSO or credentials)

# Optional: Prowler K8s CronJob (weekly scan)
kubectl apply -f .claudesec-prowler/prowler-rbac.yaml --context <dev-cluster>
kubectl apply -f .claudesec-prowler/prowler-cronjob.yaml --context <dev-cluster>

Docker

# Start dashboard (nginx, port 11777)
docker compose up -d dashboard

# Endpoints:
#   http://localhost:11777           → ISMS Dashboard
#   http://localhost:11777/scan.html → ClaudeSec Scan Dashboard

Directory Structure

claudesec/
├── run-all.sh                          # One-command: scan + build + serve
├── scripts/
│   ├── build-dashboard.py              # Dashboard data collection & HTML build
│   ├── asset-gsheet-sync.py            # Google Sheets sync
│   ├── collect-assets.sh               # Multi-source asset collector
│   ├── run-prowler-k8s.sh              # Prowler K8s scan (CronJob-based)
│   └── full-asset-sync.py              # Full sync to Google Sheets
├── claudesec-asset-dashboard.html      # Dashboard template (no data)
├── .claudesec-prowler/
│   ├── prowler-rbac.yaml               # K8s ServiceAccount + ClusterRole
│   └── prowler-cronjob.yaml            # Weekly Prowler CronJob
├── scanner/                            # ClaudeSec security scanner
├── docker-compose.yml                  # Docker stack
└── Dockerfile.nginx                    # Dashboard serving

Privacy: All scan results, asset data, and dashboard files with real data are in .gitignore. Only templates and scripts are committed. No PII, company info, or credentials are included in the repository.

Scanner CLI

ClaudeSec includes a zero-dependency bash scanner that checks your project for security best practices across 10 categories (~120+ checks). Optionally integrates with Prowler for deep multi-cloud scanning.

Scanner anchors

• Quick Start
• CI Templates
• OAuth and Token Policy
• SaaS Live Scan

Scanner Quick Start

# From repo root
./scripts/run-scan.sh
./scripts/run-scan.sh --docker

# Direct CLI
./scanner/claudesec scan -d .
./scanner/claudesec scan --category cloud
./scanner/claudesec scan --severity high,critical
./scanner/claudesec scan --format json

Scanner CI Templates

# Prowler deep scan (requires prowler)
./scanner/claudesec scan -c prowler --aws-profile audit

# AWS SSO all profiles
./scanner/claudesec scan -c prowler --aws-sso-all
AWS_SSO_LOGIN_TIMEOUT=20 CLAUDESEC_CI=1 CI=true ./scanner/claudesec scan -c prowler --aws-sso-all -f json

# Strict SSO mode for templates/prowler.yml
# vars.CLAUDESEC_STRICT_SSO=1

# Token-expiry gate vars for templates/prowler.yml / templates/security-scan-suite.yml
# vars.GH_TOKEN_EXPIRES_AT=2026-03-20T09:00:00Z
# vars.OKTA_OAUTH_TOKEN_EXPIRES_AT=2026-03-20T09:00:00Z
# vars.CLAUDESEC_TOKEN_EXPIRY_GATE_MODE=24h
# vars.CLAUDESEC_TOKEN_EXPIRY_PROVIDERS=github,okta,datadog,slack
# vars.CLAUDESEC_TOKEN_EXPIRY_STRICT_PROVIDERS=true
# vars.CLAUDESEC_DD_ARTIFACT_RETENTION_DAYS=30   # valid range: 1-90

Reusable workflow components:

• .github/actions/token-expiry-gate
• .github/actions/datadog-ci-collect

Scanner OAuth and Token Policy

Okta recommends scoped OAuth 2.0 access tokens over SSWS API tokens for automation.

• Preferred: OKTA_OAUTH_TOKEN
• Fallback: OKTA_API_TOKEN
• Strict scope check: CLAUDESEC_STRICT_OKTA_SCOPES=1
• Required scopes override: CLAUDESEC_OKTA_REQUIRED_SCOPES

export OKTA_ORG_URL="https://dev-123456.okta.com"
export OKTA_OAUTH_TOKEN="<okta-oauth-access-token>"
export GH_TOKEN="<github-token>"
export CLAUDESEC_OKTA_REQUIRED_SCOPES="okta.users.read,okta.policies.read,okta.logs.read"
export CLAUDESEC_STRICT_OKTA_SCOPES=1
./scanner/claudesec scan -c saas

Scanner SaaS Live Scan

# SaaS API scan
./scanner/claudesec scan -c saas

# Dashboard with token expiry windows
export OKTA_OAUTH_TOKEN_EXPIRES_AT="2026-03-13T09:00:00Z"
export GH_TOKEN_EXPIRES_AT="2026-03-13T08:30:00Z"
export CLAUDESEC_TOKEN_EXPIRY_WARNING_24H="24h"
export CLAUDESEC_TOKEN_EXPIRY_WARNING_7D="7d"
./scanner/claudesec dashboard --serve --host 127.0.0.1 --port 11665

# Optional: populate OAuth readiness cards via ~/.claudesec.env (auto-loaded)
cat > ~/.claudesec.env <<'EOF'
GH_TOKEN=<github-token>
GITHUB_TOKEN_EXPIRES_AT=2026-03-20T09:00:00Z
OKTA_OAUTH_TOKEN=<okta-oauth-token>
OKTA_OAUTH_TOKEN_EXPIRES_AT=2026-03-20T09:00:00Z
EOF
./run --no-serve

# Datadog local auto-fetch
DD_API_KEY=<your-dd-api-key> DD_APP_KEY=<your-dd-app-key> DD_SITE=datadoghq.com ./scanner/claudesec dashboard

CI reproducibility check (dashboard regression gate)

Use a deterministic check in CI to catch dashboard generation regressions:

./scripts/run-dashboard-docker.sh --quick --no-serve --build
./scripts/run-dashboard-docker.sh --no-serve
test -f claudesec-dashboard.html
grep -q "ClaudeSec local security scanner results" claudesec-dashboard.html

Advanced scanner examples (AWS SSO role troubleshooting, kubeconfig/prowler, Microsoft source filter, Datadog troubleshooting) are kept in:

• docs/guides/getting-started.md
• docs/guides/workflow-components.md
• docs/guides/saas-best-practices-scans.md

Datadog Required Tag Contract

Use these required tags across CI workflow templates when querying/sending Datadog logs:

• service:<workflow-service-name> (example: service:prowler)
• env:ci
• ci_pipeline_id:${{ github.run_id }}

Contract query format:

service:${DD_SERVICE} env:${DD_ENV} ci_pipeline_id:${CI_PIPELINE_ID}

Datadog ingest contract (CI log intake):

POST /v1/input?ddtags=service:${DD_SERVICE},env:${DD_ENV},ci_pipeline_id:${CI_PIPELINE_ID}

Recommended reusable env keys in workflow templates:

env:
  DD_SERVICE: <workflow-service-name>
  DD_ENV: ci
  CI_PIPELINE_ID: ${{ github.run_id }}

네트워크·보안 툴 (Network & security tools)
The dashboard includes a 네트워크·보안 툴 tab when you run the network category. It aggregates:

• Trivy — vulnerability and misconfiguration scan (filesystem + config); results in .claudesec-network/ and in the dashboard.
• Nmap / SSLScan — optional; enable in .claudesec.yml with network_scan_enabled: true and network_scan_targets: "host:443" (only scan hosts you are authorized to scan).

See templates/claudesec-network.example.yml for config. Trivy runs by default when installed; Nmap/SSLScan run only when explicitly enabled and targets are set.

Scanner Categories

Project Structure

claudesec/
├── assets/              # Logo and branding (see BRANDING.md)
├── scanner/             # Security scanner CLI (bash, zero dependencies)
│   ├── claudesec        # Main CLI entry point
│   ├── lib/             # Output formatting, helper functions
│   └── checks/          # Check modules (infra, ai, network, cloud, cicd, access-control, macos, windows, saas, prowler)
├── docs/
│   ├── devsecops/       # DevSecOps practices, OWASP, supply chain, cloud, K8s
│   ├── github/          # GitHub security features and workflows
│   ├── ai/              # AI/LLM security, MITRE ATLAS, prompt injection
│   ├── compliance/      # NIST CSF 2.0, ISO 27001/42001, KISA ISMS-P
│   ├── architecture/   # Draw.io diagrams (scanner, flow, security domains)
│   └── guides/          # Getting started, compliance mapping, branding
├── templates/           # GitHub Actions workflow templates, example configs
├── scripts/             # Security automation scripts (run, setup, run-full-dashboard)
├── hooks/               # Claude Code security hooks
├── examples/            # Example configurations
└── .github/             # Issue templates, CI workflows

Documentation

• Branding — Logo and visual identity (docs/branding.md)

DevSecOps

AI Security

GitHub Security

Compliance

Guides

Templates

Ready-to-use GitHub Actions workflows:

Reusable Workflow Components

Hooks

Claude Code security hooks for real-time protection:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "bash hooks/security-lint.sh"
      }
    ]
  }
}

See hooks/README.md for details.

ISMS Compliance Mapping

ClaudeSec scanner checks are mapped to major compliance frameworks. Each finding includes a compliance reference for audit evidence.

Full mapping details: docs/guides/compliance-mapping.md

Supported Frameworks

Security Coverage Map

                    ClaudeSec Coverage
┌──────────────────────────────────────────────────┐
│  PLAN          BUILD          TEST         DEPLOY │
│  ┌──────┐     ┌──────┐     ┌──────┐     ┌──────┐│
│  │Threat│     │Secret│     │SAST  │     │CSPM  ││
│  │Model │     │Scan  │     │DAST  │     │IaC   ││
│  │Design│     │SCA   │     │Pentest│    │K8s   ││
│  │Review│     │SBOM  │     │Fuzz  │     │Cloud ││
│  └──────┘     └──────┘     └──────┘     └──────┘│
│                                                   │
│  MONITOR       COMPLY        AI SAFETY            │
│  ┌──────┐     ┌──────┐     ┌──────┐              │
│  │Audit │     │SOC2  │     │LLM   │              │
│  │Alert │     │ISO   │     │ATLAS │              │
│  │SIEM  │     │NIST  │     │Agent │              │
│  │IR    │     │PCI   │     │RAG   │              │
│  └──────┘     └──────┘     └──────┘              │
└──────────────────────────────────────────────────┘

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Areas We Need Help

• Language-specific security guides (Python, Go, Rust, Java)
• Additional CI/CD integrations (GitLab CI, Azure DevOps)
• Real-world case studies and incident post-mortems
• Translations (i18n) — especially Korean, Japanese, Chinese
• Custom CodeQL queries and Semgrep rules
• Kubernetes admission policies (Kyverno/OPA)

Acknowledgments

• Cloud security patterns from prowler-cloud/prowler
• Audit framework informed by querypie/audit-points
• Web security based on OWASP Top 10 2025
• AI security guidance from MITRE ATLAS and OWASP LLM Top 10
• Built for the Claude Code ecosystem

Support this project

If ClaudeSec helps your DevSecOps or AI-assisted security workflow, consider giving it a star on GitHub — it helps others discover the project.

Star History

License

MIT License — see LICENSE for details.