stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

old sprints work, new sprints for exposing functionality via cli, improve code_of_conduct and other agents instructions

Browse Source
This commit is contained in:
master
2026-01-15 18:37:59 +02:00
parent c631bacee2
commit 88a85cdd92
208 changed files with 32271 additions and 2287 deletions
Download Patch File Download Diff File Expand all files Collapse all files

272
docs/api/evidence-decision-api.openapi.yaml
View File

@@ -4,7 +4,8 @@ info:
description: |
REST API for evidence retrieval and decision recording.
Sprint: SPRINT_3602_0001_0001
version: 1.0.0
Updated: SPRINT_20260112_005_BE_evidence_card_api (EVPCARD-BE-002)
version: 1.1.0
license:
name: AGPL-3.0-or-later
url: https://www.gnu.org/licenses/agpl-3.0.html
@@ -196,6 +197,81 @@ paths:
'404':
$ref: '#/components/responses/NotFound'
# Sprint: SPRINT_20260112_005_BE_evidence_card_api (EVPCARD-BE-002)
/evidence-packs/{packId}/export:
get:
operationId: exportEvidencePack
summary: Export evidence pack in various formats
description: |
Exports an evidence pack in the specified format. Supports JSON, signed JSON,
Markdown, HTML, PDF, and evidence-card formats.
**Evidence Card formats** (v1.1):
- `evidence-card`: Full evidence card with SBOM excerpt, DSSE envelope, and Rekor receipt
- `card-compact`: Compact evidence card without full SBOM
tags:
- EvidencePacks
parameters:
- name: packId
in: path
required: true
schema:
type: string
description: Evidence pack identifier
- name: format
in: query
required: false
schema:
type: string
enum: [json, signedjson, markdown, md, html, pdf, evidence-card, evidencecard, card, card-compact, evidencecardcompact]
default: json
description: |
Export format. Format aliases:
- `evidence-card`, `evidencecard`, `card` → Evidence Card
- `card-compact`, `evidencecardcompact` → Compact Evidence Card
responses:
'200':
description: Exported evidence pack
headers:
X-Evidence-Pack-Id:
schema:
type: string
description: Evidence pack identifier
X-Content-Digest:
schema:
type: string
description: SHA-256 content digest of the pack
X-Evidence-Card-Version:
schema:
type: string
description: Evidence card schema version (only for evidence-card formats)
X-Rekor-Log-Index:
schema:
type: integer
format: int64
description: Rekor transparency log index (only for evidence-card formats with Rekor receipt)
content:
application/json:
schema:
$ref: '#/components/schemas/EvidencePackExport'
application/vnd.stellaops.evidence-card+json:
schema:
$ref: '#/components/schemas/EvidenceCard'
text/markdown:
schema:
type: string
text/html:
schema:
type: string
application/pdf:
schema:
type: string
format: binary
'404':
$ref: '#/components/responses/NotFound'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
bearerAuth:
@@ -432,3 +508,197 @@ components:
type: string
instance:
type: string
# Sprint: SPRINT_20260112_005_BE_evidence_card_api (EVPCARD-BE-002)
EvidencePackExport:
type: object
required:
- pack_id
- format
- content_type
- file_name
properties:
pack_id:
type: string
description: Evidence pack identifier
format:
type: string
enum: [json, signedjson, markdown, html, pdf, evidence-card, evidence-card-compact]
description: Export format used
content_type:
type: string
description: MIME content type
file_name:
type: string
description: Suggested filename for download
content_digest:
type: string
description: SHA-256 digest of the content
EvidenceCard:
type: object
description: |
Single-file evidence card packaging SBOM excerpt, DSSE envelope, and Rekor receipt.
Designed for offline verification and audit trail.
required:
- card_id
- version
- pack_id
- created_at
- subject
- envelope
properties:
card_id:
type: string
description: Unique evidence card identifier
version:
type: string
description: Evidence card schema version (e.g., "1.0.0")
pack_id:
type: string
description: Source evidence pack identifier
created_at:
type: string
format: date-time
description: Card creation timestamp (ISO 8601 UTC)
subject:
$ref: '#/components/schemas/EvidenceCardSubject'
envelope:
$ref: '#/components/schemas/DsseEnvelope'
sbom_excerpt:
$ref: '#/components/schemas/SbomExcerpt'
rekor_receipt:
$ref: '#/components/schemas/RekorReceipt'
content_digest:
type: string
description: SHA-256 digest of canonical card content
EvidenceCardSubject:
type: object
required:
- type
properties:
type:
type: string
enum: [finding, cve, component, image, policy, custom]
finding_id:
type: string
cve_id:
type: string
component:
type: string
description: Component PURL
image_digest:
type: string
DsseEnvelope:
type: object
description: Dead Simple Signing Envelope (DSSE) per https://github.com/secure-systems-lab/dsse
required:
- payload_type
- payload
- signatures
properties:
payload_type:
type: string
description: Media type of the payload
payload:
type: string
format: byte
description: Base64-encoded payload
signatures:
type: array
items:
$ref: '#/components/schemas/DsseSignature'
DsseSignature:
type: object
required:
- sig
properties:
keyid:
type: string
description: Key identifier
sig:
type: string
format: byte
description: Base64-encoded signature
SbomExcerpt:
type: object
description: Relevant excerpt from the SBOM for the evidence subject
properties:
format:
type: string
enum: [spdx-2.2, spdx-2.3, cyclonedx-1.5, cyclonedx-1.6]
component_name:
type: string
component_version:
type: string
component_purl:
type: string
licenses:
type: array
items:
type: string
vulnerabilities:
type: array
items:
type: string
RekorReceipt:
type: object
description: Sigstore Rekor transparency log receipt for offline verification
required:
- log_index
- log_id
- integrated_time
properties:
log_index:
type: integer
format: int64
description: Rekor log index
log_id:
type: string
description: Rekor log ID (base64-encoded SHA-256 of public key)
integrated_time:
type: integer
format: int64
description: Unix timestamp when entry was integrated
inclusion_proof:
$ref: '#/components/schemas/InclusionProof'
inclusion_promise:
$ref: '#/components/schemas/SignedEntryTimestamp'
InclusionProof:
type: object
description: Merkle tree inclusion proof for log entry
properties:
log_index:
type: integer
format: int64
root_hash:
type: string
format: byte
tree_size:
type: integer
format: int64
hashes:
type: array
items:
type: string
format: byte
SignedEntryTimestamp:
type: object
description: Signed Entry Timestamp (SET) from Rekor
properties:
log_id:
type: string
format: byte
integrated_time:
type: integer
format: int64
signature:
type: string
format: byte

105
docs/api/findings-scoring.md
View File

@@ -112,6 +112,111 @@ Content-Type: application/json
}
```
### Attested-Reduction Mode (v1.1)
When attested-reduction scoring is enabled on the policy, the response includes additional fields for cryptographic attestation metadata and reduction profile information.
**Extended Response (200 OK) with Reduction Mode:**
```json
{
"findingId": "CVE-2024-1234@pkg:deb/debian/curl@7.64.0-4",
"score": 0,
"bucket": "Watchlist",
"inputs": { "rch": 0.00, "rts": 0.00, "bkp": 1.00, "xpl": 0.30, "src": 0.90, "mit": 1.00 },
"weights": { "rch": 0.30, "rts": 0.25, "bkp": 0.15, "xpl": 0.15, "src": 0.10, "mit": 0.10 },
"flags": ["anchored-vex", "vendor-na", "attested-reduction"],
"explanations": [
"Anchored VEX statement: not_affected - score reduced to 0"
],
"caps": { "speculativeCap": false, "notAffectedCap": false, "runtimeFloor": false },
"policyDigest": "sha256:reduction123...",
"calculatedAt": "2026-01-15T14:30:00Z",
"cachedUntil": "2026-01-15T15:30:00Z",
"fromCache": false,
"reductionProfile": {
"enabled": true,
"mode": "aggressive",
"profileId": "attested-verified",
"maxReductionPercent": 100,
"requireVexAnchoring": true,
"requireRekorVerification": true
},
"hardFail": false,
"shortCircuitReason": "anchored_vex_not_affected",
"anchor": {
"anchored": true,
"envelopeDigest": "sha256:abc123def456...",
"predicateType": "https://stellaops.io/attestation/vex/v1",
"rekorLogIndex": 12345678,
"rekorEntryId": "24296fb24b8ad77a7e...",
"scope": "finding",
"verified": true,
"attestedAt": "2026-01-14T10:00:00Z"
}
}
```
### Attested-Reduction Fields
| Field | Type | Description |
|-------|------|-------------|
| `reductionProfile` | object | Reduction profile configuration (when enabled) |
| `reductionProfile.enabled` | boolean | Whether attested-reduction is active |
| `reductionProfile.mode` | string | `"aggressive"` or `"conservative"` |
| `reductionProfile.profileId` | string | Profile identifier for audit trail |
| `reductionProfile.maxReductionPercent` | integer | Maximum score reduction allowed (0-100) |
| `reductionProfile.requireVexAnchoring` | boolean | Whether VEX must be anchored to qualify |
| `reductionProfile.requireRekorVerification` | boolean | Whether Rekor verification is required |
| `hardFail` | boolean | `true` if anchored evidence confirms active exploitation |
| `shortCircuitReason` | string | Reason for short-circuit (if score was short-circuited) |
| `anchor` | object | Primary evidence anchor metadata (if available) |
### Short-Circuit Reasons
| Reason | Score Effect | Condition |
|--------|--------------|-----------|
| `anchored_vex_not_affected` | Score = 0 | Verified VEX not_affected/fixed attestation |
| `anchored_affected_runtime_confirmed` | Score = 100 (hard fail) | Anchored VEX affected + anchored runtime confirms vulnerability |
### Evidence Anchor Fields
| Field | Type | Description |
|-------|------|-------------|
| `anchor.anchored` | boolean | Whether evidence has cryptographic attestation |
| `anchor.envelopeDigest` | string | DSSE envelope digest (sha256 hex) |
| `anchor.predicateType` | string | Attestation predicate type URL |
| `anchor.rekorLogIndex` | integer | Sigstore Rekor transparency log index |
| `anchor.rekorEntryId` | string | Rekor entry UUID |
| `anchor.scope` | string | Attestation scope (finding, package, image) |
| `anchor.verified` | boolean | Whether attestation signature was verified |
| `anchor.attestedAt` | string | ISO-8601 attestation timestamp |
### Hard-Fail Response Example
When anchored evidence confirms active exploitation:
```json
{
"findingId": "CVE-2024-9999@pkg:npm/critical@1.0.0",
"score": 100,
"bucket": "ActNow",
"flags": ["anchored-vex", "anchored-runtime", "hard-fail", "attested-reduction"],
"explanations": [
"Anchored VEX affected + runtime confirmed vulnerable path - hard fail"
],
"hardFail": true,
"shortCircuitReason": "anchored_affected_runtime_confirmed",
"reductionProfile": {
"enabled": true,
"mode": "aggressive",
"profileId": "attested-verified",
"maxReductionPercent": 100,
"requireVexAnchoring": true,
"requireRekorVerification": true
}
}
```
### Score Buckets
| Bucket | Score Range | Action |

26
docs/api/triage-export-api-reference.md
View File

@@ -282,6 +282,32 @@ else
fi
```
## Evidence Card Format (v1.1)
For single-file evidence exports with offline verification support, use the Evidence Pack API's evidence-card format:
```
GET /v1/evidence-packs/{packId}/export?format=evidence-card
```
### Formats
| Format | Content-Type | Description |
|--------|--------------|-------------|
| `evidence-card` | `application/vnd.stellaops.evidence-card+json` | Full evidence card with SBOM excerpt, DSSE envelope, and Rekor receipt |
| `card-compact` | `application/vnd.stellaops.evidence-card-compact+json` | Compact card without full SBOM |
### Response Headers
| Header | Description |
|--------|-------------|
| `X-Evidence-Pack-Id` | Pack identifier |
| `X-Content-Digest` | SHA-256 content digest |
| `X-Evidence-Card-Version` | Schema version (e.g., "1.0.0") |
| `X-Rekor-Log-Index` | Rekor transparency log index (when available) |
See [Evidence Decision API](./evidence-decision-api.openapi.yaml) for complete schema.
## See Also
- [Evidence Bundle Format Specification](../modules/cli/guides/commands/evidence-bundle-format.md)