# StellaOps Secret Detection Rule Bundles

This directory contains pre-compiled rule bundles for secret leak detection. These bundles are used for offline/air-gapped deployments and are signed for integrity verification.

## Directory Structure

```
bundles/
├── 2026.01/                              # CalVer versioned bundle
│   ├── secrets.ruleset.manifest.json     # Bundle manifest with metadata and rule index
│   └── secrets.ruleset.rules.jsonl       # Compiled rules in JSON Lines format
└── README.md
```

## Bundle Format

### Manifest File (`secrets.ruleset.manifest.json`)

The manifest contains:
- **schemaVersion**: Bundle schema version
- **id**: Unique bundle identifier
- **version**: CalVer version (YYYY.MM format)
- **createdAt**: ISO 8601 UTC timestamp
- **rules**: Array of rule summaries (id, version, category, severity, enabled)
- **integrity**: Hash algorithm and digest of the rules file
- **statistics**: Rule counts by severity and category

### Rules File (`secrets.ruleset.rules.jsonl`)

Each line is a complete rule definition in JSON format containing:
- **id**: Unique rule identifier (e.g., "stellaops.secrets.aws-access-key")
- **version**: SemVer version
- **name**: Human-readable name
- **description**: Detailed description
- **type**: Detection type ("regex" or "entropy")
- **pattern**: Regex pattern for regex-type rules
- **severity**: "critical", "high", "medium", or "low"
- **confidence**: "high", "medium", or "low"
- **keywords**: Array of keywords for pre-filtering
- **filePatterns**: File glob patterns to match
- **enabled**: Whether the rule is active
- **tags**: Categorization tags

## Usage

### Loading a Bundle via CLI

```bash
# Create a new bundle from sources
stellaops secrets bundle create ./sources --output ./bundles/2026.02 --version 2026.02

# Verify bundle integrity
stellaops secrets bundle verify ./bundles/2026.01

# Show bundle info
stellaops secrets bundle info ./bundles/2026.01
```

### Loading a Bundle Programmatically

```csharp
var loader = serviceProvider.GetRequiredService<IRulesetLoader>();
var ruleset = await loader.LoadFromBundleAsync("./bundles/2026.01", ct);

// Use with SecretsAnalyzer
var analyzer = new SecretsAnalyzerHost(ruleset, options);
var results = await analyzer.AnalyzeAsync(files, ct);
```

## Offline Kit Integration

Bundles are included in the Offline Kit export under `rules/secrets/`. During import, the bundle signature is verified against the Attestor trust store before activation.

See [Offline Kit Documentation](../../../docs/24_OFFLINE_KIT.md) for details.

## Rule Categories

| Category | Description | Example Rules |
|----------|-------------|---------------|
| cloud | Cloud provider credentials | AWS, Azure, GCP keys |
| credentials | Generic passwords and secrets | Connection strings, passwords |
| api-keys | Third-party API keys | Datadog, SendGrid, Stripe |
| registry | Package registry tokens | NPM, NuGet, PyPI |
| scm | Source control tokens | GitHub, GitLab PATs |
| crypto | Cryptographic keys | Private keys (RSA, EC, SSH) |
| payment | Payment processor keys | Stripe secret keys |
| webhook | Webhook URLs | Slack webhooks |

## Severity Levels

| Severity | Description |
|----------|-------------|
| critical | Immediate credential exposure risk (cloud keys, private keys) |
| high | High-value tokens with significant access (PATs, API keys) |
| medium | Limited-scope credentials or lower confidence detections |
| low | Informational findings, potential false positives |

## Contributing New Rules

1. Create a new rule JSON file in `sources/` following the schema
2. Run validation: `stellaops secrets bundle create ./sources --output ./test-bundle --validate-only`
3. Submit PR with the new rule file
4. New bundles are built automatically during release

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 2026.01 | 2026-01-04 | Initial release with 30 rules |