# 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.

## Related

- [CLI Reference: discover](cli/discover.md)
- [Configuration Reference](configuration/index.md)
- [Getting Started](../getting-started/index.md)
