partly or unimplemented features - now implemented
This commit is contained in:
master
@@ -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/)
|
||||
|
||||
Reference in New Issue
Block a user