Skip to content

Security

Jump to bottom
Lisa edited this page Jan 15, 2026 · 2 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
Azure Storage AccountKey=..., connection strings Critical
GCP Credentials Service accounts, ya29... OAuth tokens Critical/High
Twilio Account SID (AC...), Auth Token High/Critical
Slack Tokens xoxb-..., xoxp-... High
Google API Keys AIza... High
SendGrid SG.... API keys High
NPM/PyPI Tokens npm_..., pypi-... High
Database URIs MongoDB, PostgreSQL, MySQL, Redis with passwords 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

# Output in SARIF format (for GitHub Code Scanning)
ckb scan-secrets --output=sarif > results.sarif

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

Output Formats

Format Flag Use Case
JSON --output=json Default, programmatic processing
Human --output=human CLI-friendly readable output
SARIF --output=sarif GitHub Code Scanning, IDE integration

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

Git Hooks Setup (v8.1)

CKB can automatically install git hooks to scan for secrets before commits.

Quick Setup

# Install secret scanning hook (recommended)
ckb setup hooks --secrets

# Install all available hooks (secrets + impact analysis)
ckb setup hooks --all

# Generate .pre-commit-config.yaml for pre-commit framework users
ckb setup hooks --pre-commit

Available Hooks

Hook Description Behavior
--secrets Scan staged files for secrets Blocks commit if secrets found
--impact Analyze change impact Warns on high-risk changes
--all Install both hooks Combined behavior

Pre-commit Framework Integration

If you use the pre-commit framework, generate a config:

ckb setup hooks --pre-commit

This creates .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: ckb-secrets
        name: CKB Secret Scan
        entry: bash -c 'ckb scan-secrets --scope=staged --min-severity=high ...'
        language: system
        stages: [commit]
        pass_filenames: false

      - id: ckb-impact
        name: CKB Impact Analysis
        entry: bash -c 'ckb impact diff --staged ...'
        language: system
        stages: [commit]

Then run:

pre-commit install

CI/CD Integration

GitHub Actions Workflow

CKB provides a comprehensive security audit workflow with 8 configurable scanners. Each scanner can be independently enabled/disabled via environment variables.

Available Scanners

Scanner Type Description Env Variable
CKB Secrets Secret Detection Built-in 38+ pattern scanner SCAN_CKB_SECRETS
Gitleaks Secret Detection 100+ community patterns SCAN_GITLEAKS
TruffleHog Secret Detection Verified active secrets SCAN_TRUFFLEHOG
Gosec SAST Go security checker SCAN_GOSEC
Semgrep SAST Multi-language SAST SCAN_SEMGREP
govulncheck Vulnerability Go vulnerability database SCAN_GOVULNCHECK
Trivy Vulnerability Vuln + license + SBOM SCAN_TRIVY
OSV-Scanner Vulnerability Google OSV database SCAN_OSV

Workflow Configuration

Add to .github/workflows/security-audit.yml:

name: Security Audit

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop, 'feature/**']
  schedule:
    - cron: '0 6 * * 1'  # Weekly on Monday
  workflow_dispatch:
    inputs:
      scan_history:
        description: 'Scan git history (slower but more thorough)'
        required: false
        default: 'false'
        type: boolean

# ============================================================================
# Security Scan Configuration (opt-out: set to 'false' to disable)
# ============================================================================
env:
  # Secret Detection
  SCAN_CKB_SECRETS: 'true'      # CKB builtin secret scanner
  SCAN_GITLEAKS: 'true'         # Gitleaks secret detection
  SCAN_TRUFFLEHOG: 'true'       # TruffleHog verified secrets

  # SAST (Static Application Security Testing)
  SCAN_GOSEC: 'true'            # Go security checker
  SCAN_SEMGREP: 'true'          # Multi-language SAST

  # Dependency & Vulnerability Scanning
  SCAN_GOVULNCHECK: 'true'      # Go vulnerability database
  SCAN_TRIVY: 'true'            # Trivy vuln + license + SBOM
  SCAN_OSV: 'true'              # Google OSV database

  # Minimum severity for reporting (critical, high, medium, low)
  MIN_SEVERITY: 'high'

permissions:
  contents: read
  security-events: write
  pull-requests: write

Consolidated PR Comment

The workflow produces a single consolidated security audit comment on PRs that includes:

  • Secret Detection summary from CKB, Gitleaks, and TruffleHog
  • SAST Findings from Gosec and Semgrep
  • Vulnerability Report from govulncheck, Trivy, and OSV-Scanner
  • License Compliance status from Trivy
  • SBOM Generation confirmation (CycloneDX format)

Example PR comment:

🔐 Security Audit Results

📊 Summary
┌────────────────────┬──────────┬────────┐
│ Category           │ Findings │ Status │
├────────────────────┼──────────┼────────┤
│ Secrets (CKB)      │ 0        │ ✅     │
│ Secrets (Gitleaks) │ 0        │ ✅     │
│ Secrets (Trufflehog)│ 0       │ ✅     │
│ SAST (Gosec)       │ 2        │ ⚠️     │
│ SAST (Semgrep)     │ 0        │ ✅     │
│ Vulnerabilities    │ 0        │ ✅     │
│ License Issues     │ 0        │ ✅     │
└────────────────────┴──────────┴────────┘

Simple Workflow (Minimal)

For a simpler setup with just CKB secret scanning:

name: Security Audit
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  secret-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version-file: 'go.mod'

      - name: Build CKB
        run: go build -o ckb ./cmd/ckb

      - name: Initialize CKB
        run: ./ckb init

      - name: Scan for secrets
        run: |
          ./ckb scan-secrets --min-severity=high --output=json > secrets.json
          FINDINGS=$(jq -r '.summary.totalFindings // 0' secrets.json)
          if [ "$FINDINGS" -gt 0 ]; then
            echo "::warning::Found $FINDINGS potential secrets"
          fi

      - name: Upload SARIF results
        if: always()
        run: ./ckb scan-secrets --min-severity=high --output=sarif > results.sarif

      - name: Upload to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif

SARIF Integration

SARIF (Static Analysis Results Interchange Format) enables integration with:

  • GitHub Code Scanning - Results appear in Security tab
  • VS Code - SARIF Viewer extension
  • Azure DevOps - Native SARIF support
# Generate SARIF output
ckb scan-secrets --output=sarif > results.sarif

# Validate SARIF (optional)
# https://sarifweb.azurewebsites.net/Validation

Simple Pre-commit Hook

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

# Scan only staged files
result=$(ckb scan-secrets --scope=staged --min-severity=high --output=json)
findings=$(echo "$result" | jq -r '.summary.totalFindings // 0')

if [ "$findings" -gt 0 ]; then
    echo "ERROR: $findings secret(s) detected in staged files!"
    ckb scan-secrets --scope=staged --min-severity=high --output=human
    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 (ckb setup hooks --secrets)
  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
  7. Use SARIF for GitHub - Enable Code Scanning integration with --output=sarif

Builtin Patterns

CKB includes 38 builtin detection patterns across these categories:

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
  • Azure Storage Account Key (AccountKey=...)
  • Azure Connection String
  • GCP Service Account Key (JSON)
  • Twilio Auth Token

High Severity

  • GitHub Refresh Token (ghr_...)
  • Slack Bot Token (xoxb-...)
  • Slack User Token (xoxp-...)
  • Slack App Token (xapp-...)
  • Google API Key (AIza...)
  • GCP OAuth Token (ya29...)
  • Heroku API Key
  • Twilio Account SID (AC...)
  • SendGrid API Key (SG...)
  • NPM Token (npm_...)
  • PyPI Token (pypi-...)
  • Password in URL
  • Basic Auth Header
  • MongoDB Connection URI
  • PostgreSQL Connection URI
  • MySQL Connection URI
  • Redis Connection URI

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