Configuration

vigil is configured via a YAML file, CLI flags, or a combination of both. Configuration follows a three-layer model with progressive merging.

Precedence Order

Defaults (code) < YAML file (.vigil.yaml) < CLI flags

CLI flags always have the highest priority. This allows having a base configuration file for the team and making adjustments per execution.

Configuration File

Creation

# Generate with defaults
vigil init

# Generate with strict strategy
vigil init --strategy strict

# Generate in a specific directory
vigil init /path/to/project

Supported Names

vigil automatically looks for these files, in this order:

1. .vigil.yaml
2. .vigil.yml
3. vigil.yaml
4. vigil.yml

The search starts in the current directory and goes up the directory tree to the root. This allows having a configuration file at the root of a monorepo that applies to all subprojects.

Specifying an Explicit Path

vigil scan src/ --config /path/to/my-config.yaml

---

Complete Reference

General Configuration

# Directories to include in the scan
include:
  - "src/"
  - "lib/"
  - "app/"

# Directories and patterns to exclude
exclude:
  - "node_modules/"
  - ".venv/"
  - "__pycache__/"
  - ".git/"
  - "dist/"
  - "build/"
  - ".tox/"
  - ".mypy_cache/"

# Test directories (used by the `vigil tests` subcommand)
test_dirs:
  - "tests/"
  - "test/"
  - "__tests__/"

# Minimum severity to fail with exit code 1
# Options: critical, high, medium, low
fail_on: "high"

# Languages to scan
# Options: python, javascript
languages:
  - python
  - javascript

Dependencies (deps)

Configuration for the dependency analyzer (CAT-01).

deps:
  # Verify package existence on PyPI/npm via HTTP
  verify_registry: true

  # Minimum age in days to consider a package safe
  # Packages newer than this trigger DEP-002
  min_age_days: 30

  # Minimum weekly downloads to consider a package safe
  # Packages with fewer downloads trigger DEP-004
  min_weekly_downloads: 100

  # Similarity threshold for typosquatting detection (0.0 to 1.0)
  # Higher values = fewer false positives, more false negatives
  # 0.85 is a good balance
  similarity_threshold: 0.85

  # TTL for registry response cache (in hours)
  # Avoids making the same HTTP request twice in 24 hours
  cache_ttl_hours: 24

  # Offline mode: do not make any HTTP requests
  # Only runs static checks (similarity, undeclared imports)
  offline_mode: false

  # Path to a custom popular packages file (JSON)
  # By default uses the bundled corpus in data/
  # popular_packages_file: "/path/to/my-packages.json"

Authentication (auth)

Configuration for the authentication patterns analyzer (CAT-02).

auth:
  # Maximum JWT lifetime in hours
  # Tokens with a longer lifetime trigger AUTH-003
  max_token_lifetime_hours: 24

  # Require authentication on mutating endpoints (PUT, DELETE, PATCH)
  # If true, mutating endpoints without auth middleware trigger AUTH-002
  require_auth_on_mutating: true

  # Allow CORS with localhost in development mode
  # If true, `cors(origin: 'http://localhost:*')` does not trigger AUTH-005
  cors_allow_localhost: true

Secrets (secrets)

Configuration for the secrets and credentials analyzer (CAT-03).

secrets:
  # Minimum Shannon entropy (bits/character) to consider a string as a secret
  # Typical values: < 3.0 = placeholder, > 4.5 = real secret
  min_entropy: 3.0

  # Compare values in code with those in .env.example
  # If a value in code matches one from .env.example, triggers SEC-006
  check_env_example: true

  # Regex patterns for known placeholders
  # If a value assigned to a sensitive variable matches these patterns, triggers SEC-001
  placeholder_patterns:
    - "changeme"
    - "your-.*-here"
    - "TODO"
    - "FIXME"
    - "xxx+"
    - "sk-your.*"
    - "pk_test_.*"
    - "secret123"
    - "password123"
    - "supersecret"
    - "example\\.com"
    - "localhost"

Test Quality (tests)

Configuration for the test quality analyzer (CAT-06).

tests:
  # Minimum assertions required per test function
  # Tests with fewer assertions trigger TEST-001
  min_assertions_per_test: 1

  # Detect trivial assertions (assert True, assert x is not None)
  detect_trivial_asserts: true

  # Detect mocks that exactly replicate the implementation
  detect_mock_mirrors: true

Output

output:
  # Output format: human, json, junit, sarif
  format: "human"

  # Output file (null = stdout)
  output_file: null

  # Use ANSI colors in the terminal
  colors: true

  # Verbose output
  verbose: false

  # Show fix suggestions
  show_suggestions: true

---

Rule Overrides

You can disable individual rules or change their severity.

rules:
  # Disable a rule completely
  AUTH-003:
    enabled: false

  # Change the severity of a rule
  DEP-004:
    severity: "low"

  # Combine: enable with a different severity
  TEST-002:
    enabled: true
    severity: "high"

Common Overrides

rules:
  # If your project intentionally uses long-lived tokens
  AUTH-003:
    enabled: false

  # If you have internal dependencies with few downloads
  DEP-004:
    severity: "low"

  # If you allow open CORS in development
  AUTH-005:
    severity: "medium"

  # If your tests use a custom framework without standard assertions
  TEST-001:
    enabled: false

---

Predefined Strategies

strict

For environments with high compliance requirements (SOC 2, ISO 27001, EU CRA).

fail_on: "medium"
deps:
  min_age_days: 60
  min_weekly_downloads: 500
auth:
  max_token_lifetime_hours: 1

standard (default)

For most projects. Balance between security and practicality.

fail_on: "high"
deps:
  min_age_days: 30
  min_weekly_downloads: 100
auth:
  max_token_lifetime_hours: 24

relaxed

For prototypes, proofs of concept, or early-stage projects.

fail_on: "critical"
deps:
  min_age_days: 7
  min_weekly_downloads: 10
auth:
  max_token_lifetime_hours: 72

---

Per-Environment Configuration

A common practice is to have multiple configuration files:

project/
  .vigil.yaml            # Team's base config (committed)
  .vigil.strict.yaml     # Config for production
  .vigil.dev.yaml        # Config for local development

# Local development
vigil scan src/

# CI pipeline for production
vigil scan src/ --config .vigil.strict.yaml

---

Environment Variables

vigil does not read environment variables directly for its configuration. All configuration is done via YAML or CLI flags. This is intentional to keep the tool deterministic and avoid unexpected behavior.

If you need dynamic configuration, you can generate the YAML file as part of your pipeline:

# Example: dynamically generate config based on environment
if [ "$CI" = "true" ]; then
    vigil scan src/ --config .vigil.strict.yaml --fail-on medium
else
    vigil scan src/ --fail-on high
fi

---

Cache

vigil stores registry response cache (PyPI/npm) at:

~/.cache/vigil/registry/

• The default TTL is 24 hours (configurable with deps.cache_ttl_hours).
• Each package is cached individually as a JSON file.
• The cache is shared between executions to avoid repeated requests.

Clearing the Cache

rm -rf ~/.cache/vigil/registry/

Disabling the Cache

There is no explicit option to disable it. You can use cache_ttl_hours: 0 to force fresh requests on every execution, or --offline to not make any requests at all.