Skip to content

Security

Jump to bottom
Lisa edited this page Jan 15, 2026 · 3 revisions

Security Features

CKB provides security analysis tools to help detect and prevent security issues in your codebase. The primary feature is Secret Detection, which scans for exposed credentials, API keys, and other sensitive information.

Secret Detection (v8.0)

The scanSecrets tool detects exposed secrets in your codebase using pattern matching and entropy analysis.

What It Detects

Secret Type Examples Severity
AWS Credentials AKIA..., aws_secret_key=... Critical
GitHub Tokens ghp_..., gho_..., ghu_... Critical
Stripe Keys sk_live_..., rk_live_... Critical
Private Keys -----BEGIN RSA PRIVATE KEY----- Critical
Slack Tokens xoxb-..., xoxp-... High
Google API Keys AIza... High
NPM/PyPI Tokens npm_..., pypi-... High
JWT Tokens eyJ... Medium
Generic API Keys api_key=... (with entropy check) Medium
Passwords in URLs ://user:pass@host High

Usage

CLI

# Scan current directory
ckb scan-secrets

# Scan specific paths
ckb scan-secrets --paths="src/**/*.ts"

# Scan only critical/high severity
ckb scan-secrets --min-severity=high

# Scan git history (slower, more thorough)
ckb scan-secrets --scope=history --max-commits=100

# Scan only staged files (useful as pre-commit hook)
ckb scan-secrets --scope=staged

MCP Tool

{
  "tool": "scanSecrets",
  "params": {
    "scope": "workdir",
    "minSeverity": "high",
    "paths": ["src/**/*.ts"],
    "excludePaths": ["vendor/*", "node_modules/*"]
  }
}

Scan Scopes

Scope Description Use Case
workdir Current working directory files Default, quick scan
staged Only git staged files Pre-commit hooks
history Git commit history Security audits, incident response

Parameters

Parameter Type Default Description
scope string workdir What to scan: workdir, staged, history
paths array all files Limit scan to these paths (glob patterns)
excludePaths array common excludes Skip these paths
minSeverity string low Minimum severity: critical, high, medium, low
sinceCommit string - For history scope: scan commits since this ref
maxCommits int 100 For history scope: limit commits for performance
useGitleaks bool false Use gitleaks if installed (more patterns)
useTrufflehog bool false Use trufflehog if installed (verified secrets)
applyAllowlist bool true Apply configured false positive suppressions

Output

{
  "findings": [
    {
      "file": "config/settings.go",
      "line": 42,
      "type": "aws_access_key",
      "severity": "critical",
      "match": "AKIA****************",
      "rule": "aws_access_key_id",
      "confidence": 0.95,
      "source": "builtin"
    }
  ],
  "summary": {
    "totalFindings": 3,
    "bySeverity": { "critical": 1, "high": 2 },
    "filesWithSecrets": 2
  }
}

False Positive Handling

Automatic Filtering

The scanner automatically filters common false positives:

  • Example/placeholder values (EXAMPLE_KEY, your_api_key)
  • Test values (test123, changeme, dummy)
  • Documentation patterns (<your-key-here>)
  • Low-entropy strings that match generic patterns

Allowlist Configuration

Create .ckb/secrets-allowlist.json to suppress known false positives:

{
  "version": "1.0",
  "entries": [
    {
      "id": "test-files",
      "type": "path",
      "value": "**/*_test.go",
      "reason": "Test files contain mock credentials"
    },
    {
      "id": "example-docs",
      "type": "pattern",
      "value": "EXAMPLE",
      "reason": "Documentation examples"
    },
    {
      "id": "known-safe-key",
      "type": "hash",
      "value": "a1b2c3d4e5f6",
      "reason": "Public test API key"
    },
    {
      "id": "disable-generic",
      "type": "rule",
      "value": "generic_api_key",
      "reason": "Too many false positives in this codebase"
    }
  ]
}

Allowlist Entry Types:

Type Value Description
path glob pattern Suppress all findings in matching files
pattern regex Suppress findings where secret matches
hash finding hash Suppress specific finding instance
rule rule name Disable entire detection rule

External Tool Integration

For more comprehensive scanning, CKB can optionally integrate with external tools:

Gitleaks

# Install gitleaks
brew install gitleaks  # macOS
# or
go install github.com/gitleaks/gitleaks/v8@latest

# Use with CKB
ckb scan-secrets --use-gitleaks

Benefits:

  • 100+ additional patterns
  • Maintained by security community
  • Git history scanning optimized

Trufflehog

# Install trufflehog
brew install trufflehog  # macOS
# or
pip install trufflehog

# Use with CKB
ckb scan-secrets --use-trufflehog

Benefits:

  • Verified secrets (confirms if credentials are active)
  • Entropy-based detection
  • Multiple source types

Presets

scanSecrets is included in these presets:

Preset Description
review PR reviews - catch secrets before merge
refactor Security audits during code changes 
ckb mcp --preset=review

CI/CD Integration

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Scan only staged files
result=$(ckb scan-secrets --scope=staged --min-severity=high)
if echo "$result" | grep -q '"totalFindings":[1-9]'; then
    echo "ERROR: Secrets detected in staged files!"
    echo "$result" | jq '.findings[]'
    exit 1
fi

GitHub Actions

name: Security Scan
on: [push, pull_request]

jobs:
  secrets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for history scan

      - name: Install CKB
        run: npm install -g @tastehub/ckb

      - name: Scan for secrets
        run: |
          ckb init
          ckb scan-secrets --min-severity=high --output=json > secrets.json
          if [ $(jq '.summary.totalFindings' secrets.json) -gt 0 ]; then
            echo "::error::Secrets detected!"
            jq '.findings[]' secrets.json
            exit 1
          fi

Best Practices

  1. Run in CI/CD - Catch secrets before they're committed
  2. Use pre-commit hooks - Prevent secrets from entering git history
  3. Scan history after incidents - Find and rotate exposed credentials
  4. Maintain allowlist - Reduce noise from known false positives
  5. Use external tools - gitleaks/trufflehog for comprehensive coverage
  6. Rotate immediately - If a real secret is found, rotate it first, then remove from code

Builtin Patterns

CKB includes 26 builtin detection patterns:

Critical Severity:

  • AWS Access Key ID (AKIA...)
  • AWS Secret Key
  • GitHub Personal Access Token (ghp_...)
  • GitHub OAuth Token (gho_...)
  • GitHub App Token (ghu_..., ghs_...)
  • GitHub Fine-Grained PAT
  • Stripe Live Secret Key (sk_live_...)
  • Stripe Live Restricted Key (rk_live_...)
  • RSA/EC/OpenSSH/DSA/PGP Private Keys

High Severity:

  • GitHub Refresh Token (ghr_...)
  • Slack Bot Token (xoxb-...)
  • Slack User Token (xoxp-...)
  • Slack App Token (xapp-...)
  • Google API Key (AIza...)
  • NPM Token (npm_...)
  • PyPI Token (pypi-...)
  • Password in URL
  • Basic Auth Header

Medium Severity:

  • Slack Webhook URL
  • JWT Token
  • Generic API Key (entropy > 3.5)
  • Generic Secret/Password (entropy > 3.0)
  • Bearer Token

Low Severity:

  • Stripe Test Key (sk_test_...)

Risk Audit Integration

The existing auditRisk tool includes a security_sensitive factor that identifies files handling security-related code (authentication, encryption, credentials handling). Combined with scanSecrets, you get comprehensive security coverage:

# Find risky security-sensitive code
ckb audit --factor=security_sensitive

# Then scan those files for actual secrets
ckb scan-secrets --paths="internal/auth/*"

Related Features

Clone this wiki locally