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

partly or unimplemented features - now implemented

Browse Source
This commit is contained in:
master
2026-02-09 08:53:51 +02:00
parent 1bf6bbf395
commit 4bdc298ec1
674 changed files with 90194 additions and 2271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/modules/concelier/connectors.md
View File

@@ -14,7 +14,7 @@ This index lists Concelier connectors, their status, authentication expectations
| Ubuntu USN | `ubuntu` | stable | none | [docs/modules/concelier/operations/connectors/ubuntu.md](docs/modules/concelier/operations/connectors/ubuntu.md) |
| Red Hat OVAL/CSAF | `redhat` | stable | none | [docs/modules/concelier/operations/connectors/redhat.md](docs/modules/concelier/operations/connectors/redhat.md) |
| SUSE OVAL/CSAF | `suse` | stable | none | [docs/modules/concelier/operations/connectors/suse.md](docs/modules/concelier/operations/connectors/suse.md) |
| Astra Linux | `astra` | beta | none | [docs/modules/concelier/operations/connectors/astra.md](docs/modules/concelier/operations/connectors/astra.md) |
| Astra Linux | `astra` | stable | none | [docs/modules/concelier/operations/connectors/astra.md](docs/modules/concelier/operations/connectors/astra.md) |
| CISA KEV | `kev` | stable | none | [docs/modules/concelier/operations/connectors/cve-kev.md](docs/modules/concelier/operations/connectors/cve-kev.md) |
| CISA ICS-CERT | `ics-cisa` | stable | none | [docs/modules/concelier/operations/connectors/ics-cisa.md](docs/modules/concelier/operations/connectors/ics-cisa.md) |
| CERT-CC | `cert-cc` | stable | none | [docs/modules/concelier/operations/connectors/cert-cc.md](docs/modules/concelier/operations/connectors/cert-cc.md) |

86
docs/modules/concelier/federation-operations.md
View File

@@ -496,3 +496,89 @@ DSSE envelope contains:
4. **Rotate signing keys periodically**
5. **Audit import events**
6. **Monitor for duplicate bundle imports**
## Snapshot Pinning and Rollback
> **Sprint:** SPRINT_20260208_035_Concelier_feed_snapshot_coordinator
### Overview
Snapshot pinning provides cross-instance coordination for federated deployments. It ensures that:
- All federated sites can synchronize to a common snapshot version
- Failed imports are automatically rolled back to the previous stable state
- Concurrent snapshot operations are detected and prevented
### Services
The following services are registered by `AddConcelierFederationServices()`:
| Service | Description |
|---------|-------------|
| `IFeedSnapshotPinningService` | Low-level snapshot pinning using SyncLedgerRepository |
| `ISnapshotIngestionOrchestrator` | High-level orchestration with automatic rollback |
### Automatic Rollback on Import Failure
When importing a snapshot bundle, the `ISnapshotIngestionOrchestrator` provides:
1. **Lock acquisition** - Prevents concurrent operations on the same source
2. **Conflict detection** - Checks for cursor conflicts before proceeding
3. **Pin-before-import** - Pins the snapshot ID before import begins
4. **Automatic rollback** - On import failure, automatically reverts to previous state
```csharp
// Example usage in application code
var result = await orchestrator.ImportWithRollbackAsync(
inputStream,
importOptions,
sourceId,
cancellationToken);
if (!result.Success)
{
if (result.WasRolledBack)
{
_logger.LogWarning(
"Import failed but rolled back to {SnapshotId}",
result.RolledBackToSnapshotId);
}
}
```
### API Endpoints
The snapshot pinning service is available through the existing feed snapshot endpoints:
```
POST /api/v1/feeds/snapshot/import
```
When the orchestrator is used, the response includes rollback information:
```json
{
"success": false,
"error": "Import failed: invalid bundle format",
"was_rolled_back": true,
"rolled_back_to_snapshot_id": "snapshot-2024-001"
}
```
### Configuration
Snapshot pinning uses the same `FederationOptions` as other federation features:
```yaml
Federation:
Enabled: true
SiteId: "site-us-west-1" # Required for pinning coordination
```
### Monitoring
Key metrics for snapshot pinning:
- `snapshot_pin_success_total` - Successful pin operations
- `snapshot_pin_failure_total` - Failed pin operations
- `snapshot_rollback_total` - Rollback operations triggered
- `snapshot_conflict_total` - Conflict detections

164
docs/modules/concelier/operations/connectors/astra.md
View File

@@ -1,27 +1,167 @@
# Concelier Astra Linux Connector - Operations Runbook
_Last updated: 2026-01-16_
_Last updated: 2026-02-09_
## 1. Overview
The Astra Linux connector ingests regional Astra advisories and maps them to Astra package versions.
The Astra Linux connector ingests security advisories from the Astra Linux OVAL database and maps them to canonical Advisory records for use in policy decisions and vulnerability management.
### 1.1 Data Source
- **Format**: OVAL XML (Open Vulnerability and Assessment Language)
- **Source**: Astra Linux official OVAL repository
- **Coverage**: Astra Linux SE (Special Edition) packages
- **Versioning**: Debian EVR (Epoch:Version-Release) format
### 1.2 Trust Vector
| Dimension | Score | Rationale |
| --- | --- | --- |
| Provenance | 0.95 | Official FSTEC-certified source, government-backed |
| Coverage | 0.90 | Comprehensive for Astra-specific packages |
| Replayability | 0.85 | OVAL XML is structured and deterministic |
## 2. Authentication
- No authentication required for public feeds unless a mirrored source enforces access controls.
- No authentication required for public OVAL feeds.
- Mirror deployments may require access controls configured at the mirror level.
## 3. Configuration (`concelier.yaml`)
```yaml
concelier:
sources:
astra:
baseUri: "<astra-advisory-base>"
maxDocumentsPerFetch: 20
fetchTimeout: "00:00:45"
requestDelay: "00:00:00"
bulletinBaseUri: "https://astra.ru/en/support/security-bulletins/"
ovalRepositoryUri: "https://download.astralinux.ru/astra/stable/oval/"
maxDefinitionsPerFetch: 100
requestTimeout: "00:02:00"
requestDelay: "00:00:00.500"
failureBackoff: "00:15:00"
initialBackfill: "365.00:00:00"
resumeOverlap: "7.00:00:00"
userAgent: "StellaOps.Concelier.Astra/1.0 (+https://stella-ops.org)"
```
## 4. Offline and air-gapped deployments
- Mirror Astra advisories into the Offline Kit and repoint `baseUri` to the mirror.
### 3.1 Configuration Options
## 5. Common failure modes
- Regional mirror availability.
- Non-standard versioning metadata.
| Option | Default | Description |
| --- | --- | --- |
| `bulletinBaseUri` | - | Base URL for Astra security bulletin pages |
| `ovalRepositoryUri` | - | Base URL for OVAL database downloads |
| `maxDefinitionsPerFetch` | 100 | Maximum definitions to process per fetch cycle |
| `requestTimeout` | 2 min | HTTP request timeout for OVAL downloads |
| `requestDelay` | 500ms | Delay between requests to avoid rate limiting |
| `failureBackoff` | 15 min | Backoff period after fetch failures |
| `initialBackfill` | 365 days | How far back to look on initial sync |
| `resumeOverlap` | 7 days | Overlap window when resuming after interruption |
## 4. OVAL Parsing Pipeline
### 4.1 Pipeline Stages
1. **Fetch**: Download OVAL XML database from repository
2. **Parse**: Extract vulnerability definitions, tests, objects, and states
3. **Map**: Convert OVAL definitions to canonical Advisory records
### 4.2 OVAL Structure Mapping
| OVAL Element | Advisory Field | Notes |
| --- | --- | --- |
| `definition/@id` | fallback `advisoryKey` | Used when no CVE ID present |
| `definition/metadata/title` | `title` | |
| `definition/metadata/description` | `description` | |
| `definition/metadata/reference[@source='CVE']/@ref_id` | `advisoryKey`, `aliases` | First CVE is key, rest are aliases |
| `definition/metadata/advisory/severity` | `severity` | |
| `definition/metadata/advisory/issued/@date` | `published` | |
| `dpkginfo_object/name` | `AffectedPackage.identifier` | |
| `dpkginfo_state/evr` | `AffectedVersionRange` | Version constraints |
### 4.3 Version Comparison
- Astra Linux is Debian-based and uses **Debian EVR** (Epoch:Version-Release) versioning
- Version ranges use `rangeKind: evr` in the canonical model
- Comparison follows dpkg version comparison rules
## 5. Offline and Air-gapped Deployments
### 5.1 Mirror Setup
1. Download OVAL databases: `astra-linux-1.7-oval.xml`, etc.
2. Place in offline mirror directory
3. Update `ovalRepositoryUri` to point to local mirror
### 5.2 Offline Kit Structure
```
offline-kit/
├── concelier/
│ └── astra/
│ ├── oval/
│ │ ├── astra-linux-1.7-oval.xml
│ │ └── astra-linux-1.8-oval.xml
│ └── manifest.json
```
### 5.3 Configuration for Offline
```yaml
concelier:
sources:
astra:
ovalRepositoryUri: "file:///opt/stella-ops/offline/concelier/astra/oval/"
```
## 6. Common Failure Modes
### 6.1 Network Issues
| Symptom | Cause | Resolution |
| --- | --- | --- |
| Timeout errors | Large OVAL files | Increase `requestTimeout` |
| Connection refused | Regional blocking | Use mirror or VPN |
| Certificate errors | Proxy/firewall | Configure trusted roots |
### 6.2 Parsing Errors
| Error | Cause | Resolution |
| --- | --- | --- |
| `OvalParseException: Invalid OVAL document` | Wrong namespace or malformed XML | Validate OVAL file manually |
| Empty definitions | Missing `definitions` element | Check file is complete |
| Missing packages | No linked tests/objects/states | Check OVAL structure |
### 6.3 Rate Limiting
- Default `requestDelay: 500ms` should prevent rate limiting
- Increase delay if 429 errors occur
## 7. Monitoring and Alerting
### 7.1 Key Metrics
| Metric | Alert Threshold | Description |
| --- | --- | --- |
| `concelier_fetch_duration_seconds{source="distro-astra"}` | > 300s | Fetch taking too long |
| `concelier_parse_errors_total{source="distro-astra"}` | > 0 | Parsing failures |
| `concelier_definitions_parsed{source="distro-astra"}` | < 10 | Unusually few definitions |
### 7.2 Health Check
```bash
curl -s http://localhost:5000/health/sources/distro-astra | jq
```
## 8. Evidence Artifacts
- Parsed OVAL definitions stored in `DtoStore`
- Mapped advisories stored in `AdvisoryStore`
- Provenance records include:
- Source: `distro-astra`
- Kind: `oval-definition`
- Original definition ID
## 9. Related Documentation
- [Connector Architecture](../../architecture.md)
- [Concelier Implementation Notes](../../../../src/Concelier/__Connectors/StellaOps.Concelier.Connector.Astra/IMPLEMENTATION_NOTES.md)
- [OVAL Schema Reference](https://oval.mitre.org/language/version5.11/)