# Concelier Astra Linux Connector - Operations Runbook

_Last updated: 2026-02-09_

## 1. Overview

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 OVAL feeds.
- Mirror deployments may require access controls configured at the mirror level.

## 3. Configuration (`concelier.yaml`)

```yaml
concelier:
  sources:
    astra:
      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)"
```

### 3.1 Configuration Options

| 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/)