<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Performing Detection Validation at Scale

## Agent Tools

| Tool | Description |
|---|---|
| Run Validation | `run_validation(test_case, siem_url)` — Execute a detection validation test case. |
| Measure Coverage | `measure_coverage(rules_dir, attack_layer)` — Measure ATT&CK coverage from rule inventory. |
| Generate Report | `generate_report(results_dir)` — Generate validation summary report. |

## CLI Usage

```bash
# Run validation
node agent.js validate --test-case tests/tc-001.yml --siem-url https://siem.example.com
```

```bash
# Measure coverage
node agent.js coverage --rules-dir rules/ --attack-layer layers/enterprise.json
```

```bash
# Generate report
node agent.js report --results-dir results/
```

## Output Format

All commands return JSON with the following structure:

```json
{
  "action": "<command_name>",
  "...": "command-specific fields"
}
```

## Error Handling

- Invalid input returns `{"error": "description"}` with non-zero exit code
- JSON parsing errors are caught and reported with context
- Missing required arguments trigger argparse help display
