110 lines
3.9 KiB
Markdown
110 lines
3.9 KiB
Markdown
# 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 |
|