Add comprehensive security tests for OWASP A02, A05, A07, and A08 categories
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Export Center CI / export-ci (push) Has been cancelled
Findings Ledger CI / build-test (push) Has been cancelled
Findings Ledger CI / migration-validation (push) Has been cancelled
Findings Ledger CI / generate-manifest (push) Has been cancelled
Manifest Integrity / Validate Schema Integrity (push) Has been cancelled
Lighthouse CI / Lighthouse Audit (push) Has been cancelled
Lighthouse CI / Axe Accessibility Audit (push) Has been cancelled
Manifest Integrity / Validate Contract Documents (push) Has been cancelled
Manifest Integrity / Validate Pack Fixtures (push) Has been cancelled
Manifest Integrity / Audit SHA256SUMS Files (push) Has been cancelled
Manifest Integrity / Verify Merkle Roots (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Export Center CI / export-ci (push) Has been cancelled
Findings Ledger CI / build-test (push) Has been cancelled
Findings Ledger CI / migration-validation (push) Has been cancelled
Findings Ledger CI / generate-manifest (push) Has been cancelled
Manifest Integrity / Validate Schema Integrity (push) Has been cancelled
Lighthouse CI / Lighthouse Audit (push) Has been cancelled
Lighthouse CI / Axe Accessibility Audit (push) Has been cancelled
Manifest Integrity / Validate Contract Documents (push) Has been cancelled
Manifest Integrity / Validate Pack Fixtures (push) Has been cancelled
Manifest Integrity / Audit SHA256SUMS Files (push) Has been cancelled
Manifest Integrity / Verify Merkle Roots (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
- Implemented tests for Cryptographic Failures (A02) to ensure proper handling of sensitive data, secure algorithms, and key management. - Added tests for Security Misconfiguration (A05) to validate production configurations, security headers, CORS settings, and feature management. - Developed tests for Authentication Failures (A07) to enforce strong password policies, rate limiting, session management, and MFA support. - Created tests for Software and Data Integrity Failures (A08) to verify artifact signatures, SBOM integrity, attestation chains, and feed updates.
This commit is contained in:
213
docs/airgap/offline-bundle-format.md
Normal file
213
docs/airgap/offline-bundle-format.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# Offline Bundle Format (.stella.bundle.tgz)
|
||||
|
||||
> Sprint: SPRINT_3603_0001_0001
|
||||
> Module: ExportCenter
|
||||
|
||||
This document describes the `.stella.bundle.tgz` format for portable, signed, verifiable evidence packages.
|
||||
|
||||
## Overview
|
||||
|
||||
The offline bundle is a self-contained archive containing all evidence and artifacts needed for offline triage of security findings. Bundles are:
|
||||
|
||||
- **Portable**: Single file that can be transferred to air-gapped environments
|
||||
- **Signed**: DSSE-signed manifest for authenticity verification
|
||||
- **Verifiable**: Content-addressable with SHA-256 hashes for integrity
|
||||
- **Complete**: Contains all data needed for offline decision-making
|
||||
|
||||
## File Format
|
||||
|
||||
```
|
||||
{alert-id}.stella.bundle.tgz
|
||||
├── manifest.json # Bundle manifest (DSSE-signed)
|
||||
├── metadata/
|
||||
│ ├── alert.json # Alert metadata snapshot
|
||||
│ └── generation-info.json # Bundle generation metadata
|
||||
├── evidence/
|
||||
│ ├── reachability-proof.json # Call-graph reachability evidence
|
||||
│ ├── callstack.json # Exploitability call stacks
|
||||
│ └── provenance.json # Build provenance attestations
|
||||
├── vex/
|
||||
│ ├── decisions.ndjson # VEX decision history (NDJSON)
|
||||
│ └── current-status.json # Current VEX status
|
||||
├── sbom/
|
||||
│ ├── current.cdx.json # Current SBOM slice (CycloneDX)
|
||||
│ └── baseline.cdx.json # Baseline SBOM for diff
|
||||
├── diff/
|
||||
│ └── sbom-delta.json # SBOM delta changes
|
||||
└── attestations/
|
||||
├── bundle.dsse.json # DSSE envelope for bundle
|
||||
└── evidence.dsse.json # Evidence attestation chain
|
||||
```
|
||||
|
||||
## Manifest Schema
|
||||
|
||||
The `manifest.json` file follows this schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"bundle_format_version": "1.0.0",
|
||||
"bundle_id": "abc123def456...",
|
||||
"alert_id": "alert-789",
|
||||
"created_at": "2024-12-15T10:00:00Z",
|
||||
"created_by": "user@example.com",
|
||||
"stellaops_version": "1.5.0",
|
||||
"entries": [
|
||||
{
|
||||
"path": "metadata/alert.json",
|
||||
"hash": "sha256:...",
|
||||
"size": 1234,
|
||||
"content_type": "application/json"
|
||||
}
|
||||
],
|
||||
"root_hash": "sha256:...",
|
||||
"signature": {
|
||||
"algorithm": "ES256",
|
||||
"key_id": "signing-key-001",
|
||||
"value": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Manifest Fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `bundle_format_version` | string | Yes | Format version (semver) |
|
||||
| `bundle_id` | string | Yes | Unique bundle identifier |
|
||||
| `alert_id` | string | Yes | Source alert identifier |
|
||||
| `created_at` | ISO 8601 | Yes | Bundle creation timestamp (UTC) |
|
||||
| `created_by` | string | Yes | Actor who created the bundle |
|
||||
| `stellaops_version` | string | Yes | StellaOps version that created bundle |
|
||||
| `entries` | array | Yes | List of content entries with hashes |
|
||||
| `root_hash` | string | Yes | Merkle root of all entry hashes |
|
||||
| `signature` | object | No | DSSE signature (if signed) |
|
||||
|
||||
## Entry Schema
|
||||
|
||||
Each entry in the manifest:
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "evidence/reachability-proof.json",
|
||||
"hash": "sha256:abc123...",
|
||||
"size": 2048,
|
||||
"content_type": "application/json",
|
||||
"compression": null
|
||||
}
|
||||
```
|
||||
|
||||
## DSSE Signing
|
||||
|
||||
Bundles support DSSE (Dead Simple Signing Envelope) signing:
|
||||
|
||||
```json
|
||||
{
|
||||
"payloadType": "application/vnd.stellaops.bundle.manifest+json",
|
||||
"payload": "<base64-encoded manifest>",
|
||||
"signatures": [
|
||||
{
|
||||
"keyid": "signing-key-001",
|
||||
"sig": "<base64-encoded signature>"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Creation
|
||||
|
||||
### API Endpoint
|
||||
|
||||
```http
|
||||
GET /v1/alerts/{alertId}/bundle
|
||||
Authorization: Bearer <token>
|
||||
|
||||
Response: application/gzip
|
||||
Content-Disposition: attachment; filename="alert-123.stella.bundle.tgz"
|
||||
```
|
||||
|
||||
### Programmatic
|
||||
|
||||
```csharp
|
||||
var packager = services.GetRequiredService<IOfflineBundlePackager>();
|
||||
|
||||
var result = await packager.CreateBundleAsync(new BundleRequest
|
||||
{
|
||||
AlertId = "alert-123",
|
||||
ActorId = "user@example.com",
|
||||
IncludeVexHistory = true,
|
||||
IncludeSbomSlice = true
|
||||
});
|
||||
|
||||
// result.Content contains the tarball stream
|
||||
// result.ManifestHash contains the verification hash
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
### API Endpoint
|
||||
|
||||
```http
|
||||
POST /v1/alerts/{alertId}/bundle/verify
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"bundle_hash": "sha256:abc123...",
|
||||
"signature": "<optional DSSE signature>"
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"is_valid": true,
|
||||
"hash_valid": true,
|
||||
"chain_valid": true,
|
||||
"signature_valid": true,
|
||||
"verified_at": "2024-12-15T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Programmatic
|
||||
|
||||
```csharp
|
||||
var verification = await packager.VerifyBundleAsync(
|
||||
bundlePath: "/path/to/bundle.stella.bundle.tgz",
|
||||
expectedHash: "sha256:abc123...");
|
||||
|
||||
if (!verification.IsValid)
|
||||
{
|
||||
Console.WriteLine($"Verification failed: {string.Join(", ", verification.Errors)}");
|
||||
}
|
||||
```
|
||||
|
||||
## CLI Usage
|
||||
|
||||
```bash
|
||||
# Export bundle
|
||||
stellaops alert bundle export --alert-id alert-123 --output ./bundles/
|
||||
|
||||
# Verify bundle
|
||||
stellaops alert bundle verify --file ./bundles/alert-123.stella.bundle.tgz
|
||||
|
||||
# Import bundle (air-gapped instance)
|
||||
stellaops alert bundle import --file ./bundles/alert-123.stella.bundle.tgz
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Hash Verification**: Always verify bundle hash before processing
|
||||
2. **Signature Validation**: Verify DSSE signature if present
|
||||
3. **Content Validation**: Validate JSON schemas after extraction
|
||||
4. **Size Limits**: Enforce maximum bundle size limits (default: 100MB)
|
||||
5. **Path Traversal**: Tarball extraction must prevent path traversal attacks
|
||||
|
||||
## Versioning
|
||||
|
||||
| Format Version | Changes | Min StellaOps Version |
|
||||
|----------------|---------|----------------------|
|
||||
| 1.0.0 | Initial format | 1.0.0 |
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Evidence Bundle Envelope](./evidence-bundle-envelope.md)
|
||||
- [DSSE Signing Guide](./dsse-signing.md)
|
||||
- [Offline Kit Guide](../10_OFFLINE_KIT.md)
|
||||
- [API Reference](../api/evidence-decision-api.openapi.yaml)
|
||||
Reference in New Issue
Block a user