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

audit notes work completed, test fixes work (95% done), new sprints, new data sources setup and configuration

Browse Source
This commit is contained in:
master
2026-01-14 10:48:00 +02:00
parent d7be6ba34b
commit 95d5898650
379 changed files with 40695 additions and 19041 deletions
Download Patch File Download Diff File Expand all files Collapse all files

254
docs/modules/advisory-ai/llm-setup-guide.md Normal file
View File

@@ -0,0 +1,254 @@
# LLM Provider Setup Guide
This guide explains how to configure an LLM (Large Language Model) provider for AdvisoryAI features in StellaOps.
## Overview
AdvisoryAI uses LLM providers to power AI-assisted vulnerability analysis, advisory recommendations, and conversational assistance. You can choose from several supported providers based on your requirements for privacy, performance, and cost.
## Supported Providers
| Provider | Description | Requirements |
|----------|-------------|--------------|
| **OpenAI** | GPT-4o, GPT-4, GPT-3.5 Turbo | API key |
| **Anthropic Claude** | Claude 4 Sonnet, Claude 3.5 Sonnet, Claude 3 Opus | API key |
| **Google Gemini** | Gemini 1.5 Flash, Gemini 1.5 Pro | API key |
| **Ollama** | Local LLM (Llama 3, Mistral, etc.) | Local Ollama instance |
## Quick Start
### Using the Setup Wizard (Recommended)
Run the interactive setup wizard to configure an LLM provider:
```bash
stella setup --step llm
```
The wizard will:
1. Present available provider options
2. Prompt for required credentials
3. Test API connectivity
4. Save the configuration
### Using Environment Variables
You can also configure providers using environment variables:
```bash
# OpenAI
export OPENAI_API_KEY="sk-..."
# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."
# Google Gemini
export GEMINI_API_KEY="AIza..."
# or
export GOOGLE_API_KEY="AIza..."
```
## Provider Configuration
### OpenAI
**Configuration file:** `etc/llm-providers/openai.yaml`
```yaml
enabled: true
priority: 100
api:
apiKey: "${OPENAI_API_KEY}"
baseUrl: "https://api.openai.com/v1"
model:
name: "gpt-4o"
fallbacks:
- "gpt-4-turbo"
- "gpt-3.5-turbo"
inference:
temperature: 0.0
maxTokens: 8192
seed: 42
```
**Models available:**
- `gpt-4o` - Recommended for most use cases
- `gpt-4-turbo` - High performance, higher cost
- `gpt-4` - Previous generation
- `gpt-3.5-turbo` - Lower cost, faster
### Anthropic Claude
**Configuration file:** `etc/llm-providers/claude.yaml`
```yaml
enabled: true
priority: 100
api:
apiKey: "${ANTHROPIC_API_KEY}"
baseUrl: "https://api.anthropic.com"
model:
name: "claude-sonnet-4-20250514"
fallbacks:
- "claude-3-5-sonnet-20241022"
- "claude-3-haiku-20240307"
inference:
temperature: 0.0
maxTokens: 8192
```
**Models available:**
- `claude-sonnet-4-20250514` - Latest Sonnet model (recommended)
- `claude-3-5-sonnet-20241022` - Claude 3.5 Sonnet
- `claude-3-opus-20240229` - Highest capability
- `claude-3-haiku-20240307` - Fastest, lowest cost
### Google Gemini
**Configuration file:** `etc/llm-providers/gemini.yaml`
```yaml
enabled: true
priority: 100
api:
apiKey: "${GEMINI_API_KEY}"
baseUrl: "https://generativelanguage.googleapis.com/v1beta"
model:
name: "gemini-1.5-flash"
fallbacks:
- "gemini-1.5-pro"
- "gemini-1.0-pro"
inference:
temperature: 0.0
maxTokens: 8192
topP: 1.0
topK: 40
```
**Models available:**
- `gemini-1.5-flash` - Fast, cost-effective (recommended)
- `gemini-1.5-pro` - Higher capability
- `gemini-1.0-pro` - Previous generation
### Ollama (Local)
**Configuration file:** `etc/llm-providers/ollama.yaml`
```yaml
enabled: true
priority: 50
api:
endpoint: "http://localhost:11434"
model:
name: "llama3:8b"
fallbacks:
- "mistral:7b"
inference:
temperature: 0.0
maxTokens: 4096
```
**Prerequisites:**
1. Install Ollama: https://ollama.ai
2. Pull a model: `ollama pull llama3:8b`
3. Start Ollama: `ollama serve`
**Recommended models:**
- `llama3:8b` - Good balance of speed and capability
- `llama3:70b` - Higher capability, requires more resources
- `mistral:7b` - Fast, efficient
- `codellama:7b` - Optimized for code
## Checking Configuration
### Using Doctor
Run the Doctor checks to validate your LLM configuration:
```bash
# Check all AI-related configuration
stella doctor run --category ai
# Check specific provider
stella doctor run --check check.ai.provider.openai
stella doctor run --check check.ai.provider.claude
stella doctor run --check check.ai.provider.gemini
```
### Using the CLI
Check your AdvisoryAI chat configuration:
```bash
stella advise chat-doctor
```
## Troubleshooting
### "AI/LLM provider not configured"
This error appears when no LLM provider is configured. Solutions:
1. Run `stella setup --step llm` to configure a provider
2. Set environment variables for your preferred provider
3. Create a configuration file in `etc/llm-providers/`
### API Key Invalid
If you receive authentication errors:
1. Verify your API key is correct
2. Check the API key has not expired
3. Ensure billing is active on your provider account
4. For Gemini, ensure the Generative Language API is enabled
### Connection Timeout
If connections time out:
1. Check network connectivity to the provider endpoint
2. Verify proxy settings if behind a firewall
3. For Ollama, ensure the service is running locally
### Rate Limiting
If you encounter rate limits:
1. Reduce request frequency
2. Consider upgrading your API tier
3. Enable request queueing in configuration
## Offline/Air-Gapped Operation
For air-gapped deployments, use Ollama with locally-available models:
1. Download models on a connected system
2. Transfer model files to the air-gapped environment
3. Configure Ollama with local models
4. Set `AdvisoryAI:DefaultProvider` to `ollama`
## Security Considerations
1. **API Key Storage:** Never commit API keys to version control. Use environment variables or secure vaults.
2. **Data Privacy:** Be aware of data sent to cloud providers. Use Ollama for sensitive data.
3. **Rate Limiting:** Configure appropriate rate limits to prevent abuse.
4. **Audit Logging:** Enable audit logging for all LLM interactions.
## Related Documentation
- [AdvisoryAI Architecture](./architecture.md)
- [Chat Interface](./chat-interface.md)
- [Deployment Guide](./deployment.md)
- [Assistant Guardrails](/docs/security/assistant-guardrails.md)

19
docs/modules/binary-index/architecture.md
View File

@@ -806,6 +806,15 @@ Binary extraction and fingerprint generation MUST run with:
- `binaryindex.corpus.ingest` - Corpus ingestion
- `binaryindex.fingerprint.generate` - Fingerprint generation
### 7.3 Ops Endpoints
BinaryIndex exposes read-only ops endpoints for health, bench, cache, and effective configuration:
- GET `/api/v1/ops/binaryindex/health` -> BinaryIndexOpsHealthResponse
- POST `/api/v1/ops/binaryindex/bench/run` -> BinaryIndexBenchResponse
- GET `/api/v1/ops/binaryindex/cache` -> BinaryIndexFunctionCacheStats
- GET `/api/v1/ops/binaryindex/config` -> BinaryIndexEffectiveConfig
---
## 8. Configuration
@@ -849,6 +858,12 @@ binaryindex:
rustfs_bucket: stellaops/binaryindex
```
Additional appsettings sections (case-insensitive):
- `BinaryIndex:B2R2Pool` - lifter pool sizing and warm ISA list.
- `BinaryIndex:SemanticLifting` - LowUIR enablement and deterministic controls.
- `BinaryIndex:FunctionCache` - Valkey function cache configuration.
- `Postgres:BinaryIndex` - persistence for canonical IR fingerprints.
---
## 9. Testing Strategy
@@ -885,5 +900,5 @@ binaryindex:
---
*Document Version: 1.1.0*
*Last Updated: 2025-01-15*
*Document Version: 1.1.1*
*Last Updated: 2026-01-14*

19
docs/modules/binary-index/semantic-diffing.md
View File

@@ -473,10 +473,25 @@ binaryindex:
max_function_size_bytes: 1048576 # 1MB
```
Additional appsettings sections (case-insensitive):
- `BinaryIndex:B2R2Pool` - lifter pool sizing and warm ISA list.
- `BinaryIndex:SemanticLifting` - LowUIR enablement and deterministic controls.
- `BinaryIndex:FunctionCache` - Valkey function cache configuration.
- `Postgres:BinaryIndex` - persistence for canonical IR fingerprints.
---
## 12. Metrics & Observability
### Ops Endpoints
BinaryIndex exposes read-only ops endpoints for health, bench, cache, and effective configuration:
- GET `/api/v1/ops/binaryindex/health` -> BinaryIndexOpsHealthResponse
- POST `/api/v1/ops/binaryindex/bench/run` -> BinaryIndexBenchResponse
- GET `/api/v1/ops/binaryindex/cache` -> BinaryIndexFunctionCacheStats
- GET `/api/v1/ops/binaryindex/config` -> BinaryIndexEffectiveConfig
### Metrics
| Metric | Type | Labels |
@@ -560,5 +575,5 @@ Pre-computed test cases with known results:
---
*Document Version: 1.0.0*
*Last Updated: 2026-01-05*
*Document Version: 1.0.1*
*Last Updated: 2026-01-14*

40
docs/modules/cli/implementation_plan.md Normal file
View File

@@ -0,0 +1,40 @@
# CLI Implementation Plan
## Purpose
Provide a concise, living plan for CLI feature delivery, determinism, parity, and offline workflows.
## Active work
- `docs/implplan/SPRINT_20260112_004_CLI_reachability_trace_export.md`
- `docs/implplan/SPRINT_20260112_006_CLI_binaryindex_ops_cli.md`
- `docs/implplan/SPRINT_20260112_010_CLI_ai_code_guard_command.md`
- `docs/implplan/SPRINT_20260112_010_CLI_unknowns_grey_queue_cli.md`
- `docs/implplan/SPRINT_20260112_011_CLI_evidence_card_remediate_cli.md`
- `docs/implplan/SPRINT_20260112_014_CLI_determinization_config_viewer.md`
- `docs/implplan/SPRINT_20260112_014_CLI_witness_commands.md`
## Near-term deliverables
- Witness commands: list/show/verify/export with DSSE status and deterministic output.
- Reachability trace export in JSON and SARIF formats.
- Unknowns queue and determinization config viewer commands with stable sorting.
- Evidence card remediate workflows and AI code guard command.
- Updated docs and CLI fixtures covering new commands.
## Dependencies
- Authority for auth flows and DPoP.
- Scanner, Policy, and Attestor APIs for data and verification.
- Offline kit bundles and trust roots for verification.
- Deterministic output contract in `docs/modules/cli/contracts/output-determinism.md`.
## Evidence of completion
- Command handlers updated under `src/Cli/StellaOps.Cli/Commands`.
- Backend client updates in `src/Cli/StellaOps.Cli/Services`.
- CLI tests and golden fixtures updated under `src/Cli/__Tests/StellaOps.Cli.Tests`.
- Command documentation updated under `docs/modules/cli/guides/commands`.
## Reference docs
- `docs/modules/cli/README.md`
- `docs/modules/cli/architecture.md`
- `docs/modules/cli/contracts/output-determinism.md`
- `docs/modules/cli/contracts/install-integrity.md`
- `docs/modules/cli/guides/cli-reference.md`
- `docs/modules/platform/architecture-overview.md`

2
docs/modules/evidence-locker/architecture.md
View File

@@ -274,5 +274,7 @@ Bundle N-1 Bundle N Bundle N+1
* Bundle packaging: `./bundle-packaging.md`
* Attestation contract: `./attestation-contract.md`
* Evidence bundle spec: `./evidence-bundle-v1.md`
* Evidence pack schema: `./guides/evidence-pack-schema.md`
* Audit bundle index schema: `./schemas/audit-bundle-index.schema.json`
* ExportCenter: `../export-center/architecture.md`
* Attestor: `../attestor/architecture.md`

5
docs/modules/evidence-locker/guides/evidence-pack-schema.md
View File

@@ -15,6 +15,11 @@
- **Offline Transfer:** Move evidence between air-gapped environments
- **Forensics:** Query pack contents without external dependencies
### Transparency and timestamp references
- `transparency.rekorEntries` lists Rekor UUIDs and optional inclusion proof paths.
- `timestamps` lists RFC3161 timestamp tokens and related metadata.
- When offline, leave these arrays empty and record skip reasons in the attestation predicates.
---
## Pack Structure

111
docs/modules/evidence-locker/schemas/audit-bundle-index.schema.json Normal file
View File

@@ -0,0 +1,111 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stellaops.dev/schemas/evidence/audit-bundle-index.schema.json",
"title": "StellaOps Audit Bundle Index",
"description": "Index/manifest for audit bundles with integrity hashes and referenced artifacts.",
"type": "object",
"additionalProperties": false,
"required": [
"manifestVersion",
"bundleId",
"createdAt",
"subject",
"artifacts",
"verification"
],
"properties": {
"manifestVersion": { "type": "string", "minLength": 1 },
"bundleId": { "type": "string", "minLength": 1 },
"createdAt": { "type": "string", "format": "date-time" },
"subject": { "$ref": "#/$defs/subject" },
"artifacts": {
"type": "array",
"minItems": 1,
"items": { "$ref": "#/$defs/artifact" }
},
"verification": { "$ref": "#/$defs/verification" },
"transparency": { "$ref": "#/$defs/transparency" },
"timestamps": {
"type": "array",
"items": { "$ref": "#/$defs/timestampEntry" }
}
},
"$defs": {
"subject": {
"type": "object",
"additionalProperties": false,
"required": ["type", "digest"],
"properties": {
"type": { "type": "string", "minLength": 1 },
"digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
"name": { "type": "string" }
}
},
"artifact": {
"type": "object",
"additionalProperties": false,
"required": ["path", "type", "digest", "size"],
"properties": {
"path": { "type": "string", "minLength": 1 },
"type": { "type": "string", "minLength": 1 },
"format": { "type": "string" },
"digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
"size": { "type": "integer", "minimum": 0 },
"mediaType": { "type": "string" },
"predicateType": { "type": "string" },
"signedBy": {
"type": "array",
"items": { "type": "string" }
},
"attributes": {
"type": "object",
"additionalProperties": { "type": "string" }
}
}
},
"verification": {
"type": "object",
"additionalProperties": false,
"required": ["merkleRoot", "algorithm", "checksumFile"],
"properties": {
"merkleRoot": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
"algorithm": { "type": "string", "minLength": 1 },
"checksumFile": { "type": "string", "minLength": 1 }
}
},
"transparency": {
"type": "object",
"additionalProperties": false,
"properties": {
"rekorEntries": {
"type": "array",
"items": { "$ref": "#/$defs/rekorEntry" }
}
}
},
"rekorEntry": {
"type": "object",
"additionalProperties": false,
"required": ["uuid", "logIndex"],
"properties": {
"uuid": { "type": "string", "minLength": 1 },
"logIndex": { "type": "integer", "minimum": 0 },
"rootHash": { "type": "string" },
"inclusionProofPath": { "type": "string" },
"logUrl": { "type": "string" }
}
},
"timestampEntry": {
"type": "object",
"additionalProperties": false,
"required": ["tokenPath", "hashAlgorithm"],
"properties": {
"tokenPath": { "type": "string", "minLength": 1 },
"hashAlgorithm": { "type": "string", "minLength": 1 },
"signedAt": { "type": "string", "format": "date-time" },
"tsaName": { "type": "string" },
"tsaUrl": { "type": "string" }
}
}
}
}

169
docs/modules/evidence-locker/schemas/stellaops-evidence-pack.v1.schema.json Normal file
View File

@@ -0,0 +1,169 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stellaops.dev/schemas/evidence/stellaops-evidence-pack.v1.schema.json",
"title": "StellaOps Evidence Pack (v1)",
"description": "Deterministic evidence pack manifest for audit and replay workflows.",
"type": "object",
"additionalProperties": false,
"required": [
"_type",
"packId",
"generatedAt",
"tenantId",
"manifestVersion",
"contents"
],
"properties": {
"_type": {
"type": "string",
"const": "https://stellaops.dev/evidence-pack@v1"
},
"packId": {
"type": "string",
"minLength": 1
},
"generatedAt": {
"type": "string",
"format": "date-time",
"description": "UTC timestamp when the pack was assembled."
},
"tenantId": {
"type": "string",
"minLength": 1
},
"policyRunId": {
"type": "string"
},
"policyId": {
"type": "string"
},
"policyVersion": {
"type": "integer",
"minimum": 0
},
"manifestVersion": {
"type": "string",
"minLength": 1
},
"contents": {
"type": "object",
"additionalProperties": false,
"properties": {
"policy": { "$ref": "#/$defs/contentArray" },
"sbom": { "$ref": "#/$defs/contentArray" },
"advisories": { "$ref": "#/$defs/contentArray" },
"vex": { "$ref": "#/$defs/contentArray" },
"verdicts": { "$ref": "#/$defs/contentArray" },
"reachability": { "$ref": "#/$defs/contentArray" },
"attestations": { "$ref": "#/$defs/contentArray" }
}
},
"statistics": {
"type": "object",
"additionalProperties": false,
"properties": {
"totalFiles": { "type": "integer", "minimum": 0 },
"totalSize": { "type": "integer", "minimum": 0 },
"componentCount": { "type": "integer", "minimum": 0 },
"findingCount": { "type": "integer", "minimum": 0 },
"verdictCount": { "type": "integer", "minimum": 0 },
"advisoryCount": { "type": "integer", "minimum": 0 },
"vexStatementCount": { "type": "integer", "minimum": 0 }
}
},
"determinismHash": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
},
"signatures": {
"type": "array",
"items": { "$ref": "#/$defs/signature" }
},
"transparency": {
"type": "object",
"additionalProperties": false,
"properties": {
"rekorEntries": {
"type": "array",
"items": { "$ref": "#/$defs/rekorEntry" }
}
}
},
"timestamps": {
"type": "array",
"items": { "$ref": "#/$defs/timestampEntry" }
}
},
"$defs": {
"contentArray": {
"type": "array",
"items": { "$ref": "#/$defs/contentEntry" }
},
"contentEntry": {
"type": "object",
"additionalProperties": false,
"required": ["path", "digest", "size", "mediaType"],
"properties": {
"path": {
"type": "string",
"minLength": 1
},
"digest": {
"type": "string",
"pattern": "^(sha256|sha384|sha512):[0-9a-f]{64,128}$"
},
"size": {
"type": "integer",
"minimum": 0
},
"mediaType": {
"type": "string",
"minLength": 1
},
"capturedAt": {
"type": "string",
"format": "date-time"
},
"attributes": {
"type": "object",
"additionalProperties": { "type": "string" }
}
}
},
"signature": {
"type": "object",
"additionalProperties": false,
"required": ["keyId", "algorithm", "signature", "signedAt"],
"properties": {
"keyId": { "type": "string", "minLength": 1 },
"algorithm": { "type": "string", "minLength": 1 },
"signature": { "type": "string", "minLength": 1 },
"signedAt": { "type": "string", "format": "date-time" }
}
},
"rekorEntry": {
"type": "object",
"additionalProperties": false,
"required": ["uuid", "logIndex"],
"properties": {
"uuid": { "type": "string", "minLength": 1 },
"logIndex": { "type": "integer", "minimum": 0 },
"rootHash": { "type": "string" },
"inclusionProofPath": { "type": "string" },
"logUrl": { "type": "string" }
}
},
"timestampEntry": {
"type": "object",
"additionalProperties": false,
"required": ["tokenPath", "hashAlgorithm"],
"properties": {
"tokenPath": { "type": "string", "minLength": 1 },
"hashAlgorithm": { "type": "string", "minLength": 1 },
"signedAt": { "type": "string", "format": "date-time" },
"tsaName": { "type": "string" },
"tsaUrl": { "type": "string" }
}
}
}
}

3
docs/modules/export-center/architecture.md
View File

@@ -82,7 +82,8 @@ All endpoints require Authority-issued JWT + DPoP tokens with scopes `export:run
Audit bundles are a specialized Export Center output: a deterministic, immutable evidence pack for a single subject (and optional time window) suitable for audits and incident response.
- **Schema**: `docs/modules/evidence-locker/schemas/audit-bundle-index.schema.json` (bundle index/manifest with integrity hashes and referenced artefacts).
- **Schema**: `docs/modules/evidence-locker/schemas/audit-bundle-index.schema.json` (bundle index/manifest with integrity hashes and referenced artefacts).
- The index must list Rekor entry ids and RFC3161 timestamp tokens when present; offline bundles record skip reasons in predicates.
- **Core APIs**:
- `POST /v1/audit-bundles` - Create a new bundle (async generation).
- `GET /v1/audit-bundles` - List previously created bundles.

5
docs/modules/export-center/overview.md
View File

@@ -30,8 +30,9 @@ Refer to `docs/modules/export-center/architecture.md` (Sprint 35 task) for compo
## Security and compliance guardrails
- **AOC alignment.** Exports bundle raw evidence and optional policy evaluations without mutating source content. Policy overlays remain attributed to Policy Engine and are clearly partitioned.
- **Tenant isolation.** All queries, manifests, and bundle paths carry tenant identifiers. Cross-tenant exports require explicit signed approval and ship with provenance trails.
- **Signing and encryption.** Manifests and payloads are signed using the platform KMS. Mirror profiles support optional in-bundle encryption (age/AES-GCM) with key wrapping.
- **Determinism.** Identical inputs yield identical bundles. Timestamps serialize in UTC ISO-8601; manifests include content hashes for audit replay.
- **Signing and encryption.** Manifests and payloads are signed using the platform KMS. Mirror profiles support optional in-bundle encryption (age/AES-GCM) with key wrapping.
- **Determinism.** Identical inputs yield identical bundles. Timestamps serialize in UTC ISO-8601; manifests include content hashes for audit replay.
- **Audit bundles.** Audit packs use `docs/modules/evidence-locker/schemas/audit-bundle-index.schema.json` and list transparency and timestamp references when available.
See `docs/security/policy-governance.md` and `docs/modules/concelier/guides/aggregation-only-contract.md` for broader guardrail context.

2
docs/modules/policy/architecture.md
View File

@@ -5,7 +5,7 @@
> **Ownership:** Policy Guild • Platform Guild
> **Services:** `StellaOps.Policy.Engine` (Minimal API + worker host)
> **Data Stores:** PostgreSQL (`policy.*` schemas for packs, runs, exceptions, receipts), Object storage (explain bundles), optional queue
> **Related docs:** [Policy overview](../../policy/overview.md), [DSL](../../policy/dsl.md), [SPL v1](../../policy/spl-v1.md), [Lifecycle](../../policy/lifecycle.md), [Runtime](../../policy/runtime.md), [Governance](../../policy/governance.md), [REST API](../../policy/api.md), [Policy CLI](../cli/guides/policy.md), [Architecture overview](../platform/architecture-overview.md), [AOC reference](../../aoc/aggregation-only-contract.md)
> **Related docs:** [Policy overview](../../policy/overview.md), [DSL](../../policy/dsl.md), [SPL v1](../../policy/spl-v1.md), [Lifecycle](../../policy/lifecycle.md), [Runtime](../../policy/runtime.md), [Governance](../../policy/governance.md), [REST API](../../policy/api.md), [Policy CLI](../cli/guides/policy.md), [Architecture overview](../platform/architecture-overview.md), [AOC reference](../../aoc/aggregation-only-contract.md), [AI Code Guard policy](guides/ai-code-guard-policy.md)
This dossier describes the internal structure of the Policy Engine service delivered in Epic 2. It focuses on module boundaries, deterministic evaluation, orchestration, and integration contracts with Concelier, Excititor, SBOM Service, Authority, Scheduler, and Observability stacks.

55
docs/modules/policy/guides/ai-code-guard-policy.md Normal file
View File

@@ -0,0 +1,55 @@
# AI Code Guard Policy Guide
> **Status:** Planned
> **Audience:** Policy authors, Security reviewers, CI owners
> **Related:** `docs/modules/scanner/operations/ai-code-guard.md`
This guide defines the Policy signals and matrix logic used to evaluate AI Code Guard evidence. The goal is deterministic, explainable pass/review/block outcomes with auditable overrides.
## 1) Policy goals
- Deterministic pass/review/block outcomes for the same inputs.
- Explainable results with short reasons and evidence links.
- Overrides allowed only with issue link and expiry.
## 2) Signals (proposed)
| Signal | Type | Notes |
| --- | --- | --- |
| `guard.ai.status` | string | `pass`, `review`, `block` from Scanner. |
| `guard.ai.hunk.count` | int | Count of changed hunks evaluated. |
| `guard.ai.secrets.new.count` | int | New secrets in this change. |
| `guard.ai.secrets.pre_existing.count` | int | Previously known secrets. |
| `guard.ai.unsafe.count` | int | Unsafe API findings. |
| `guard.ai.similarity.max` | number | Highest similarity score (0.0-1.0). |
| `guard.ai.similarity.denylist_hit` | bool | True when denylist threshold is exceeded. |
| `guard.ai.license.block.count` | int | Licenses in block list. |
| `guard.ai.license.review.count` | int | Licenses requiring review. |
| `guard.ai.override.active` | bool | Override is present and unexpired. |
| `guard.ai.override.expires_at` | string | UTC ISO-8601 timestamp. |
## 3) Policy matrix
Default matrix (policy pack example):
- Block if new secrets or denylist similarity exceed thresholds.
- Review if license review count > 0 or similarity above review threshold.
- Pass otherwise.
## 4) Example DSL snippet
```dsl
rule ai_code_guard_block priority 50 {
when guard.ai.secrets.new.count > 0 or guard.ai.similarity.denylist_hit == true
then status := "block"
because "AI code guard block criteria met";
}
```
## 5) Overrides
- Overrides require issue links and expiry.
- Review overrides require `SecurityReviewer` role; block overrides require `SecurityOwner`.
- Policy explain traces must include override metadata for audit.
## 6) Evidence and replay
- Policy explain exports include the guard evidence hash and rule version.
- Guard evidence is stored and signed for deterministic replay.

3
docs/modules/scanner/architecture.md
View File

@@ -2,7 +2,8 @@
> Aligned with Epic 6 – Vulnerability Explorer and Epic 10 – Export Center.
> **Scope.** Implementation‑ready architecture for the **Scanner** subsystem: WebService, Workers, analyzers, SBOM assembly (inventory & usage), per‑layer caching, three‑way diffs, artifact catalog (RustFS default + PostgreSQL, S3-compatible fallback), attestation hand‑off, and scale/security posture. This document is the contract between the scanning plane and everything else (Policy, Excititor, Concelier, UI, CLI).
> **Scope.** Implementation‑ready architecture for the **Scanner** subsystem: WebService, Workers, analyzers, SBOM assembly (inventory & usage), per‑layer caching, three‑way diffs, artifact catalog (RustFS default + PostgreSQL, S3-compatible fallback), attestation hand‑off, and scale/security posture. This document is the contract between the scanning plane and everything else (Policy, Excititor, Concelier, UI, CLI).
> **Related:** `docs/modules/scanner/operations/ai-code-guard.md`
---

65
docs/modules/scanner/operations/ai-code-guard.md Normal file
View File

@@ -0,0 +1,65 @@
# AI Code Guard (Scanner Operations)
> **Status:** Planned
> **Audience:** Scanner operators, Security owners, CI maintainers
> **Related:** `docs/modules/policy/guides/ai-code-guard-policy.md`, `docs/benchmarks/ai-code-guard/README.md`
AI Code Guard adds fast, deterministic checks for AI-assisted code changes so security, IP, and license issues are caught before release gates. The guard runs in Scanner, emits evidence for Policy, and can be surfaced via CLI or SCM annotations.
## 1) Checks
### 1.1 Secrets and unsafe patterns
- Secrets leak detection uses the existing secrets analyzer ruleset and classifies findings as new or pre-existing via hunk hashes.
- Unsafe API detection reuses language capability scanners (eval/exec, SQL concat, weak crypto, process spawn).
- Findings include file path, line range, and masked snippets (ASCII only).
### 1.2 Attribution and similarity
- Changed hunks are normalized (line endings, whitespace, path separators) and hashed into deterministic hunk IDs.
- Similarity is evaluated against allowlist and denylist corpora shipped with Offline Kit.
- Unknown provenance over the review threshold requires justification.
### 1.3 License hygiene
- Dependency diffs are derived from SBOM changes.
- License evidence is mapped to allow/review/block verdicts using the policy matrix.
- Snippets exceeding the line threshold require a provenance comment or waiver reference.
## 2) Inputs and evidence
Inputs:
- Base and head refs (or explicit diff).
- Scanner findings (secrets and capabilities).
- SBOM inventory and license evidence.
- Allowlist and denylist corpora with pinned digests.
- Guard policy config (`.stellaops.yml`).
Evidence output:
- Deterministic JSON payload with hunk hashes, similarity scores, finding summaries, and rule versions.
- DSSE-ready bundle for Attestor registration.
Example (abbreviated):
```json
{
"status": "review",
"hunks": 4,
"secrets": { "new": 1, "pre_existing": 0 },
"unsafe_apis": 2,
"similarity": { "max": 0.87, "denylist_hit": false },
"licenses": { "block": 0, "review": 1 }
}
```
## 3) Determinism and offline posture
- Stable ordering of hunks and findings; all hashes use canonical JSON and UTF-8.
- Similarity corpora are addressed by digest and packaged in Offline Kit bundles.
- No network calls during evaluation; all inputs are local or provided by the caller.
## 4) Integration points
- Scanner WebService exposes guard run endpoints for CI and Console.
- CLI uses `stella guard run` for JSON, SARIF, and GitLab formats.
- Integrations post SCM annotations and status checks when configured.
- Attestor registers guard evidence as a predicate type for audit trails.
## 5) Overrides
Overrides are Policy-driven and require issue links plus expiry. The guard emits override metadata for audit trails; Policy decides whether to allow a time-boxed waiver.

30
docs/modules/signer/implementation_plan.md Normal file
View File

@@ -0,0 +1,30 @@
# Signer Implementation Plan
## Purpose
Define a concise, living plan for Signer DSSE signing, predicate registry, and attestor alignment.
## Active work
- `docs/implplan/SPRINT_20260112_015_SIGNER_path_witness_predicate.md`
## Near-term deliverables
- Register canonical path-witness predicate `https://stella.ops/predicates/path-witness/v1` with alias support.
- Update predicate classification helpers and allowlists for reachability types.
- Expand predicate allowlist tests and integration coverage for DSSE signing.
- Maintain cosign-compatible DSSE outputs with deterministic canonical JSON.
## Dependencies
- Authority for OpTok and Proof-of-Entitlement checks.
- Crypto provider registry and keyless or KMS backends.
- Attestor and Policy verification rules for accepted predicate types.
- Path witness contract updates in `docs/contracts/witness-v1.md`.
## Evidence of completion
- Predicate catalog updates in `src/Signer/StellaOps.Signer/StellaOps.Signer.Core/PredicateTypes.cs`.
- Tests updated under `src/Signer/__Tests`.
- DSSE bundles for path witness validate under Signer allowlist rules.
## Reference docs
- `docs/modules/signer/README.md`
- `docs/modules/signer/architecture.md`
- `docs/modules/platform/architecture-overview.md`
- `docs/contracts/witness-v1.md`