# 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: skill # 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:
| **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
| 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
|
= 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
|
= 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
| 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
```