Skip to content

AI-Powered Secret Discovery

The secretzero discover command uses artificial intelligence to automatically scan your project and generate a starter Secretfile.detect.yml — the fastest way to bootstrap your secrets configuration.

Quick Start

Bash
# Scan current directory with default settings (Ollama/local)
secretzero discover

# Privacy-first: only use local LLM models
secretzero discover --local-only

# Dry-run to preview without writing any files
secretzero discover --dry-run --no-llm

# Use OpenAI for deeper semantic analysis
secretzero discover --provider openai

How It Works

Discovery runs in two complementary stages:

  1. Pattern-based detection (always available)
    Regular-expression heuristics identify common secret patterns such as API keys, database passwords, JWT secrets, cloud credentials, and OAuth tokens. Each match receives a confidence score based on how specific and recognisable the pattern is.

  2. LLM-enhanced analysis (optional, requires secretzero[ai])
    When an LLM backend is configured and reachable, file snippets are sent to the model for deeper semantic analysis. LLM candidates are merged with pattern results and weighted by combined confidence. The analysis runs locally when Ollama is selected, so sensitive data never leaves your machine.

Output

Running secretzero discover produces Secretfile.detect.yml — a valid SecretZero configuration that you can review, edit, and merge into your Secretfile.yml:

YAML
version: "1.0"
metadata:
  description: Auto-generated by secretzero discover
  generated_by: secretzero-discovery-agent
providers:
  local:
    kind: local
    config: {}
secrets:
  - name: database_password
    description: Detected database password in .env
    kind: random_password
    config: {}
    targets:
      - provider: local
        kind: file
        config:
          path: .env
          format: dotenv
          merge: true

Configuration

Create a secretzero.yml file to control discovery behaviour:

YAML
# secretzero.yml
version: "1.0"

llm:
  default_provider: ollama   # ollama | openai | anthropic | azure_openai
  providers:
    ollama:
      base_url: "${OLLAMA_HOST:-http://localhost:11434}"
      model: "${OLLAMA_MODEL:-llama3.2:3b}"
      timeout: 120
      temperature: 0.7
    openai:
      api_key: "${OPENAI_API_KEY}"
      model: "gpt-4o-mini"
    anthropic:
      api_key: "${ANTHROPIC_API_KEY}"
      model: "claude-3-5-sonnet-20241022"

discovery:
  confidence_threshold: 0.6     # Minimum score to include (0.0–1.0)
  max_files: 1000               # Cap on files scanned
  include_patterns:
    - "*.env*"
    - "*.yml"
    - "*.yaml"
    - "*.json"
    - "*.toml"
    - "*.tf"
    - "*.tfvars"
  exclude_patterns:
    - "**/node_modules/**"
    - "**/venv/**"
    - "**/.venv/**"
    - "**/dist/**"
    - "**/build/**"
    - "**/.git/**"

output:
  format: text      # text | json | yaml
  verbosity: 1      # 0–3
  color: true

Configuration Loading Priority

The CLI loads secretzero.yml from the first location found:

  1. SECRETZERO_CONFIG environment variable (absolute path)
  2. ./secretzero.yml in the current working directory
  3. ~/.config/secretzero/secretzero.yml in your home directory

If no file is found, built-in defaults are used.

CLI Options

Option Default Description
--path / -p . Project root directory to scan
--output / -o <path>/Secretfile.detect.yml Output file path
--dry-run false Analyse without writing files
--no-llm false Pattern matching only; skip LLM
--provider From config LLM provider to use
--model From config LLM model override
--local-only false Restrict to local LLM providers
--config / -c Auto-discovered Path to secretzero.yml
--format / -f text Output format: text, json, yaml
--threshold From config Confidence threshold override

Installing AI Extras

Bash
# All AI providers (recommended)
pip install "secretzero[ai]"

# Individual providers
pip install langchain-ollama   # Ollama (local, free)
pip install langchain-openai   # OpenAI
pip install langchain-anthropic # Anthropic Claude

Privacy & Security

  • Local-only mode (--local-only or --no-llm) never sends any data to external APIs.
  • Raw secret values are never stored, logged, or included in the output. Only the variable name, description, confidence score, and recommended generator type are written to the output file.
  • Obvious placeholder values (e.g. your_api_key_here, ${VAR_NAME}, <your-secret>) are automatically skipped.

Next Steps

After running discovery:

  1. Review Secretfile.detect.yml and remove false positives.
  2. Rename or merge entries into your Secretfile.yml.
  3. Run secretzero validate to validate the merged configuration.
  4. Run secretzero sync --dry-run to preview secret generation.