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

# 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

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

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

Version History

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

README.md