axor-sentinel 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. axor_sentinel-0.1.0/.github/workflows/ci.yml +134 -0
  2. axor_sentinel-0.1.0/.gitignore +11 -0
  3. axor_sentinel-0.1.0/PKG-INFO +105 -0
  4. axor_sentinel-0.1.0/README.md +81 -0
  5. axor_sentinel-0.1.0/axor_sentinel/__init__.py +0 -0
  6. axor_sentinel-0.1.0/axor_sentinel/bench/__init__.py +0 -0
  7. axor_sentinel-0.1.0/axor_sentinel/bench/agents/__init__.py +0 -0
  8. axor_sentinel-0.1.0/axor_sentinel/bench/agents/profiles.py +88 -0
  9. axor_sentinel-0.1.0/axor_sentinel/bench/configs/__init__.py +0 -0
  10. axor_sentinel-0.1.0/axor_sentinel/bench/configs/paper_baseline.yaml +29 -0
  11. axor_sentinel-0.1.0/axor_sentinel/bench/dataset/__init__.py +0 -0
  12. axor_sentinel-0.1.0/axor_sentinel/bench/dataset/composer.py +175 -0
  13. axor_sentinel-0.1.0/axor_sentinel/bench/dataset/schema.py +78 -0
  14. axor_sentinel-0.1.0/axor_sentinel/bench/eval/__init__.py +0 -0
  15. axor_sentinel-0.1.0/axor_sentinel/bench/eval/calibration.py +146 -0
  16. axor_sentinel-0.1.0/axor_sentinel/bench/eval/metrics.py +128 -0
  17. axor_sentinel-0.1.0/axor_sentinel/bench/results.md +64 -0
  18. axor_sentinel-0.1.0/axor_sentinel/bench/scenarios/__init__.py +0 -0
  19. axor_sentinel-0.1.0/axor_sentinel/bench/scenarios/attack.py +353 -0
  20. axor_sentinel-0.1.0/axor_sentinel/bench/scenarios/benign.py +232 -0
  21. axor_sentinel-0.1.0/axor_sentinel/bench/topology/__init__.py +0 -0
  22. axor_sentinel-0.1.0/axor_sentinel/bench/topology/generator.py +167 -0
  23. axor_sentinel-0.1.0/axor_sentinel/bench/topology/pool.py +43 -0
  24. axor_sentinel-0.1.0/axor_sentinel/compatibility.py +68 -0
  25. axor_sentinel-0.1.0/axor_sentinel/graph/__init__.py +0 -0
  26. axor_sentinel-0.1.0/axor_sentinel/graph/model.py +152 -0
  27. axor_sentinel-0.1.0/axor_sentinel/graph/normalizer.py +120 -0
  28. axor_sentinel-0.1.0/axor_sentinel/graph/queries.py +191 -0
  29. axor_sentinel-0.1.0/axor_sentinel/integration/__init__.py +0 -0
  30. axor_sentinel-0.1.0/axor_sentinel/integration/core_sink.py +204 -0
  31. axor_sentinel-0.1.0/axor_sentinel/integration/intent_enricher.py +181 -0
  32. axor_sentinel-0.1.0/axor_sentinel/integration/phase.py +27 -0
  33. axor_sentinel-0.1.0/axor_sentinel/integration/probe_bridge.py +71 -0
  34. axor_sentinel-0.1.0/axor_sentinel/reports/__init__.py +0 -0
  35. axor_sentinel-0.1.0/axor_sentinel/reports/slow_and_low.py +43 -0
  36. axor_sentinel-0.1.0/axor_sentinel/sentinel/__init__.py +0 -0
  37. axor_sentinel-0.1.0/axor_sentinel/sentinel/cycle.py +510 -0
  38. axor_sentinel-0.1.0/axor_sentinel/sentinel/events.py +93 -0
  39. axor_sentinel-0.1.0/axor_sentinel/sentinel/snapshot.py +349 -0
  40. axor_sentinel-0.1.0/axor_sentinel/sentinel/weight.py +161 -0
  41. axor_sentinel-0.1.0/bench_run.py +224 -0
  42. axor_sentinel-0.1.0/docs/architecture.md +492 -0
  43. axor_sentinel-0.1.0/pyproject.toml +63 -0
  44. axor_sentinel-0.1.0/tests/__init__.py +0 -0
  45. axor_sentinel-0.1.0/tests/test_calibration.py +68 -0
  46. axor_sentinel-0.1.0/tests/test_compatibility.py +39 -0
  47. axor_sentinel-0.1.0/tests/test_core_sink.py +185 -0
  48. axor_sentinel-0.1.0/tests/test_cycle.py +364 -0
  49. axor_sentinel-0.1.0/tests/test_fanout.py +195 -0
  50. axor_sentinel-0.1.0/tests/test_integration.py +271 -0
  51. axor_sentinel-0.1.0/tests/test_normalizer.py +168 -0
  52. axor_sentinel-0.1.0/tests/test_security_fixes.py +82 -0
  53. axor_sentinel-0.1.0/tests/test_snapshot.py +193 -0
  54. axor_sentinel-0.1.0/tests/test_state_auth.py +59 -0
  55. axor_sentinel-0.1.0/tests/test_weight.py +241 -0
@@ -0,0 +1,134 @@
1
+ name: CI/CD
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ tags: ["v*.*.*"]
7
+ pull_request:
8
+ branches: [main]
9
+ repository_dispatch:
10
+ types: [axor-core-published]
11
+
12
+ jobs:
13
+ test:
14
+ name: Test (Python ${{ matrix.python-version }})
15
+ runs-on: ubuntu-latest
16
+ strategy:
17
+ matrix:
18
+ python-version: ["3.11", "3.12"]
19
+
20
+ steps:
21
+ - uses: actions/checkout@v4
22
+
23
+ - name: Log trigger context
24
+ if: github.event_name == 'repository_dispatch'
25
+ run: |
26
+ echo "Triggered by axor-core ${{ github.event.client_payload.version }}"
27
+
28
+ - uses: actions/setup-python@v5
29
+ with:
30
+ python-version: ${{ matrix.python-version }}
31
+ cache: pip
32
+
33
+ - name: Checkout axor-core
34
+ if: github.event_name != 'repository_dispatch'
35
+ uses: actions/checkout@v4
36
+ with:
37
+ repository: ${{ github.repository_owner }}/axor-core
38
+ path: axor-core
39
+
40
+ - name: Install axor-core from source
41
+ if: github.event_name != 'repository_dispatch'
42
+ run: pip install -e axor-core/
43
+
44
+ - name: Install axor-core from PyPI (pinned to triggering version)
45
+ if: github.event_name == 'repository_dispatch'
46
+ run: |
47
+ pip install "axor-core==${{ github.event.client_payload.version }}"
48
+
49
+ - name: Install
50
+ run: |
51
+ pip install -e ".[dev]"
52
+
53
+ - name: Static analysis — no axor-sentinel imports in axor-core
54
+ run: |
55
+ python - << 'EOF'
56
+ import ast, os, sys
57
+ issues = []
58
+ for root, dirs, files in os.walk("axor_sentinel"):
59
+ dirs[:] = [d for d in dirs if not d.startswith("__")]
60
+ for f in files:
61
+ if not f.endswith(".py"):
62
+ continue
63
+ path = os.path.join(root, f)
64
+ src = open(path).read()
65
+ if "import axor_core" in src or "from axor_core" in src:
66
+ # Only integration/, tests/, and the version-compat shim
67
+ # may import axor_core.
68
+ rel = os.path.relpath(path, "axor_sentinel")
69
+ if not (rel.startswith("integration") or rel.startswith("../tests") or rel == "compatibility.py"):
70
+ issues.append(f"DEPENDENCY_VIOLATION: {path} imports axor_core outside integration/")
71
+ if issues:
72
+ print("\n".join(issues))
73
+ sys.exit(1)
74
+ print("✓ dependency direction enforced")
75
+ EOF
76
+
77
+ - name: Lint
78
+ run: ruff check axor_sentinel/ tests/ bench_run.py --quiet
79
+
80
+ - name: Type check
81
+ run: mypy axor_sentinel/
82
+
83
+ - name: Run tests
84
+ run: pytest tests/ -v --tb=short
85
+
86
+ publish:
87
+ name: Publish to PyPI
88
+ needs: test
89
+ runs-on: ubuntu-latest
90
+ if: startsWith(github.ref, 'refs/tags/v')
91
+ environment: pypi
92
+
93
+ permissions:
94
+ id-token: write # for trusted publishing
95
+
96
+ steps:
97
+ - uses: actions/checkout@v4
98
+
99
+ - uses: actions/setup-python@v5
100
+ with:
101
+ python-version: "3.12"
102
+
103
+ - name: Verify tag matches package version
104
+ run: |
105
+ python - << 'EOF'
106
+ import pathlib
107
+ import re
108
+ import sys
109
+ import tomllib
110
+
111
+ ref = "${{ github.ref_name }}"
112
+ m = re.fullmatch(r"v(\d+\.\d+\.\d+)", ref)
113
+ if not m:
114
+ print(f"Tag {ref!r} must match vX.Y.Z")
115
+ sys.exit(1)
116
+
117
+ tag_version = m.group(1)
118
+ data = tomllib.loads(pathlib.Path("pyproject.toml").read_text(encoding="utf-8"))
119
+ pkg_version = data["project"]["version"]
120
+
121
+ if tag_version != pkg_version:
122
+ print(f"Version mismatch: tag={tag_version}, pyproject={pkg_version}")
123
+ sys.exit(1)
124
+
125
+ print(f"Version check passed: {pkg_version}")
126
+ EOF
127
+
128
+ - name: Build
129
+ run: |
130
+ pip install hatchling build
131
+ python -m build
132
+
133
+ - name: Publish to PyPI
134
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,11 @@
1
+ __pycache__/
2
+ *.pyc
3
+ *.pyo
4
+ .mypy_cache/
5
+ .pytest_cache/
6
+ .ruff_cache/
7
+ *.egg-info/
8
+ dist/
9
+ build/
10
+ .venv/
11
+ venv/
@@ -0,0 +1,105 @@
1
+ Metadata-Version: 2.4
2
+ Name: axor-sentinel
3
+ Version: 0.1.0
4
+ Summary: Cross-session behavioral analysis for Axor via weighted resource reputation graph
5
+ Project-URL: Repository, https://github.com/Bucha11/axor-sentinel
6
+ License: MIT
7
+ Keywords: agents,ai,governance,reputation,security
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Requires-Python: >=3.11
14
+ Provides-Extra: bench
15
+ Provides-Extra: dev
16
+ Requires-Dist: mypy>=1.10; extra == 'dev'
17
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
18
+ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
19
+ Requires-Dist: pytest>=8.0; extra == 'dev'
20
+ Requires-Dist: ruff>=0.4; extra == 'dev'
21
+ Provides-Extra: neo4j
22
+ Requires-Dist: neo4j>=5; extra == 'neo4j'
23
+ Description-Content-Type: text/markdown
24
+
25
+ # axor-sentinel
26
+
27
+ Cross-session behavioral analysis layer for axor-core. Detects **slow-and-low staging attacks** — coordinated data exfiltration spread across many sessions over days or weeks — that are invisible to per-session anomaly detection.
28
+
29
+ ## The problem it solves
30
+
31
+ Per-session anomaly detectors see each session in isolation. An attacker staging an exfiltration across dozens of short, individually normal sessions — touching sensitive resources a little each time, then exfiltrating later — never exceeds any single-session threshold.
32
+
33
+ axor-sentinel maintains a **resource reputation graph** across all sessions. Resources accumulate suspicion over time; when a highly reputated resource is accessed in a new session, axor-core can deny the request deterministically before any LLM inference.
34
+
35
+ ## How it works
36
+
37
+ ```
38
+ sessions (axor-core)
39
+ │
40
+ ▼
41
+ SentinelCycle ← background audit, runs every ~1h
42
+ ├── time decay ← scores halve every 30 days
43
+ ├── hot weights ← READ=0.4 / READ_SUMMARIZE=0.6 / EXPORT_ADJACENT=0.8 / EXPORT_FAILED=1.0
44
+ ├── caution weights ← adjacent resources get BASE_CAUTION=0.3 × topology_factor
45
+ ├── fanout detection ← z-score vs agent's historical baseline (fires at z > 2.5)
46
+ └── snapshot swap ← atomic write to disk (symlink rename / os.replace)
47
+ │
48
+ ▼
49
+ ReputationSnapshot ← flat dict resource_id → score, loaded at startup
50
+ │
51
+ ▼
52
+ SnapshotIntentEnricher ← populates NormalizedIntent.target_resource_reputation
53
+ │
54
+ ▼
55
+ IntentLoop (axor-core) ← Phase 1: score ≥ 0.8 + after_external_read → deterministic deny
56
+ ```
57
+
58
+ Score accumulation uses **logarithmic diminishing returns** — each signal contributes proportionally to remaining headroom, so scores are bounded to `[0, 1]` and saturate naturally:
59
+
60
+ ```
61
+ new_score = current + new_weight × (1 − current)
62
+ ```
63
+
64
+ ## Quick start
65
+
66
+ ```bash
67
+ pip install -e ".[neo4j]"
68
+ ```
69
+
70
+ ```python
71
+ from pathlib import Path
72
+ from axor_sentinel.sentinel.cycle import SentinelCycle
73
+ from axor_sentinel.integration.intent_enricher import SnapshotIntentEnricher
74
+
75
+ # Background audit cycle (runs hourly, not on hot path)
76
+ cycle = SentinelCycle(neo4j_session, snapshot_dir=Path("~/.axor/sentinel"))
77
+ snapshot = cycle.run_once(sessions)
78
+
79
+ # Hot-path enrichment — pure dict lookup, no Neo4j
80
+ enricher = SnapshotIntentEnricher.from_dir(Path("~/.axor/sentinel"))
81
+
82
+ # Wire into axor-core IntentLoop:
83
+ loop = IntentLoop(..., reputation_enricher=enricher)
84
+ ```
85
+
86
+ ## Bench suite
87
+
88
+ 820-scenario synthetic dataset (paper baseline):
89
+
90
+ ```bash
91
+ pip install -e ".[bench]"
92
+ ```
93
+
94
+ ```python
95
+ from axor_sentinel.bench.dataset.composer import DatasetComposer
96
+ from axor_sentinel.bench.eval.metrics import evaluate
97
+
98
+ scenarios = DatasetComposer().compose() # 820 scenarios, seed=42
99
+ result = evaluate(scenarios, scores=my_scores)
100
+ print(result.tpr_at_fpr_budget) # TPR @ FPR ≤ 0.02
101
+ ```
102
+
103
+ ---
104
+
105
+ See [docs/architecture.md](docs/architecture.md) for the full design: graph schema, weight model, invariants, attack patterns, and bench composition.
@@ -0,0 +1,81 @@
1
+ # axor-sentinel
2
+
3
+ Cross-session behavioral analysis layer for axor-core. Detects **slow-and-low staging attacks** — coordinated data exfiltration spread across many sessions over days or weeks — that are invisible to per-session anomaly detection.
4
+
5
+ ## The problem it solves
6
+
7
+ Per-session anomaly detectors see each session in isolation. An attacker staging an exfiltration across dozens of short, individually normal sessions — touching sensitive resources a little each time, then exfiltrating later — never exceeds any single-session threshold.
8
+
9
+ axor-sentinel maintains a **resource reputation graph** across all sessions. Resources accumulate suspicion over time; when a highly reputated resource is accessed in a new session, axor-core can deny the request deterministically before any LLM inference.
10
+
11
+ ## How it works
12
+
13
+ ```
14
+ sessions (axor-core)
15
+ │
16
+ ▼
17
+ SentinelCycle ← background audit, runs every ~1h
18
+ ├── time decay ← scores halve every 30 days
19
+ ├── hot weights ← READ=0.4 / READ_SUMMARIZE=0.6 / EXPORT_ADJACENT=0.8 / EXPORT_FAILED=1.0
20
+ ├── caution weights ← adjacent resources get BASE_CAUTION=0.3 × topology_factor
21
+ ├── fanout detection ← z-score vs agent's historical baseline (fires at z > 2.5)
22
+ └── snapshot swap ← atomic write to disk (symlink rename / os.replace)
23
+ │
24
+ ▼
25
+ ReputationSnapshot ← flat dict resource_id → score, loaded at startup
26
+ │
27
+ ▼
28
+ SnapshotIntentEnricher ← populates NormalizedIntent.target_resource_reputation
29
+ │
30
+ ▼
31
+ IntentLoop (axor-core) ← Phase 1: score ≥ 0.8 + after_external_read → deterministic deny
32
+ ```
33
+
34
+ Score accumulation uses **logarithmic diminishing returns** — each signal contributes proportionally to remaining headroom, so scores are bounded to `[0, 1]` and saturate naturally:
35
+
36
+ ```
37
+ new_score = current + new_weight × (1 − current)
38
+ ```
39
+
40
+ ## Quick start
41
+
42
+ ```bash
43
+ pip install -e ".[neo4j]"
44
+ ```
45
+
46
+ ```python
47
+ from pathlib import Path
48
+ from axor_sentinel.sentinel.cycle import SentinelCycle
49
+ from axor_sentinel.integration.intent_enricher import SnapshotIntentEnricher
50
+
51
+ # Background audit cycle (runs hourly, not on hot path)
52
+ cycle = SentinelCycle(neo4j_session, snapshot_dir=Path("~/.axor/sentinel"))
53
+ snapshot = cycle.run_once(sessions)
54
+
55
+ # Hot-path enrichment — pure dict lookup, no Neo4j
56
+ enricher = SnapshotIntentEnricher.from_dir(Path("~/.axor/sentinel"))
57
+
58
+ # Wire into axor-core IntentLoop:
59
+ loop = IntentLoop(..., reputation_enricher=enricher)
60
+ ```
61
+
62
+ ## Bench suite
63
+
64
+ 820-scenario synthetic dataset (paper baseline):
65
+
66
+ ```bash
67
+ pip install -e ".[bench]"
68
+ ```
69
+
70
+ ```python
71
+ from axor_sentinel.bench.dataset.composer import DatasetComposer
72
+ from axor_sentinel.bench.eval.metrics import evaluate
73
+
74
+ scenarios = DatasetComposer().compose() # 820 scenarios, seed=42
75
+ result = evaluate(scenarios, scores=my_scores)
76
+ print(result.tpr_at_fpr_budget) # TPR @ FPR ≤ 0.02
77
+ ```
78
+
79
+ ---
80
+
81
+ See [docs/architecture.md](docs/architecture.md) for the full design: graph schema, weight model, invariants, attack patterns, and bench composition.
File without changes
File without changes
@@ -0,0 +1,88 @@
1
+ from __future__ import annotations
2
+
3
+ import random
4
+ from dataclasses import dataclass
5
+
6
+
7
+ @dataclass
8
+ class AgentProfile:
9
+ """
10
+ Statistical profile of an agent's normal container access behavior.
11
+
12
+ Used to generate realistic session histories and baselines for bench scenarios.
13
+ mean_containers and std are the parameters of the normal distribution
14
+ from which unique container counts per session are sampled.
15
+ """
16
+ name: str
17
+ mean_containers: float
18
+ std: float
19
+ description: str = ""
20
+
21
+
22
+ # Standard profiles from spec §Agent profiles
23
+ PROFILES: dict[str, AgentProfile] = {
24
+ "narrow": AgentProfile(
25
+ name="narrow",
26
+ mean_containers=1.5,
27
+ std=0.5,
28
+ description="Specialized agent, tight access",
29
+ ),
30
+ "broad": AgentProfile(
31
+ name="broad",
32
+ mean_containers=6.0,
33
+ std=2.0,
34
+ description="Research agent, wide access",
35
+ ),
36
+ "noisy": AgentProfile(
37
+ name="noisy",
38
+ mean_containers=4.0,
39
+ std=3.5,
40
+ description="Unpredictable, high std",
41
+ ),
42
+ "etl": AgentProfile(
43
+ name="etl",
44
+ mean_containers=8.0,
45
+ std=1.0,
46
+ description="Wide but stable — fanout baseline absorbs",
47
+ ),
48
+ "research": AgentProfile(
49
+ name="research",
50
+ mean_containers=5.0,
51
+ std=2.5,
52
+ description="Analytical, moderate",
53
+ ),
54
+ }
55
+
56
+
57
+ class AgentProfileGenerator:
58
+ """
59
+ Samples realistic per-session container counts from an agent profile.
60
+
61
+ etl and broad are intentionally hard cases for fanout detection — they
62
+ legitimately touch many containers and must NOT trigger FanoutSignal.
63
+ """
64
+
65
+ def __init__(self, profile_name: str, rng: random.Random | None = None) -> None:
66
+ if profile_name not in PROFILES:
67
+ raise ValueError(
68
+ f"Unknown agent profile: {profile_name!r}. "
69
+ f"Valid: {list(PROFILES)}"
70
+ )
71
+ self.profile = PROFILES[profile_name]
72
+ self._rng = rng or random.Random()
73
+
74
+ def sample_containers(self) -> int:
75
+ """
76
+ Sample the number of unique containers for one session.
77
+
78
+ Returns at least 1 (agents always access something).
79
+ """
80
+ sample = self._rng.gauss(
81
+ self.profile.mean_containers,
82
+ self.profile.std,
83
+ )
84
+ return max(1, round(sample))
85
+
86
+ def generate_baseline_counts(self, n_sessions: int) -> list[int]:
87
+ """Generate n_sessions container counts for baseline computation."""
88
+ return [self.sample_containers() for _ in range(n_sessions)]
@@ -0,0 +1,29 @@
1
+ # Paper-baseline dataset composition (spec §Dataset composition)
2
+ # Total: 820 scenarios — 420 attack, 400 benign
3
+ # Seed: 42 (deterministic across runs)
4
+
5
+ seed: 42
6
+
7
+ # ── Attack scenarios ──────────────────────────────────────────
8
+ # slow_and_low: 270 total (3 variants × 90)
9
+ slow_and_low_2: 90
10
+ slow_and_low_4: 90
11
+ slow_and_low_8: 90
12
+
13
+ # fanout: 90 total (3 variants × 30)
14
+ fanout_3: 30
15
+ fanout_5: 30
16
+ fanout_10: 30
17
+
18
+ # distributed staging: 60
19
+ distributed_staging: 60
20
+
21
+ # ── Benign scenarios ──────────────────────────────────────────
22
+ # narrow: 150
23
+ benign_narrow: 150
24
+
25
+ # broad/etl (split equally): 150 total
26
+ benign_broad_etl: 150
27
+
28
+ # false-taint (most important benign variant per spec): 100
29
+ benign_false_taint: 100
@@ -0,0 +1,175 @@
1
+ from __future__ import annotations
2
+
3
+ import random
4
+ from pathlib import Path
5
+ from typing import Any
6
+
7
+ from axor_sentinel.bench.dataset.schema import Scenario
8
+ from axor_sentinel.bench.scenarios import attack as atk
9
+ from axor_sentinel.bench.scenarios import benign as ben
10
+ from axor_sentinel.bench.topology.pool import TopologyPool
11
+
12
+
13
+ # Default paper-baseline composition counts.
14
+ # NOTE: bench/configs/paper_baseline.yaml is the human-readable source of truth
15
+ # for these numbers. Changes here must be mirrored in that file (and vice versa).
16
+ # To compose directly from the YAML, use DatasetComposer.compose_from_yaml().
17
+ _PAPER_BASELINE_COUNTS: dict[str, int] = {
18
+ "slow_and_low_2": 90,
19
+ "slow_and_low_4": 90,
20
+ "slow_and_low_8": 90,
21
+ "fanout_3": 30,
22
+ "fanout_5": 30,
23
+ "fanout_10": 30,
24
+ "distributed_staging": 60,
25
+ "benign_narrow": 150,
26
+ "benign_broad_etl": 150,
27
+ "benign_false_taint": 100,
28
+ }
29
+
30
+
31
+ class DatasetComposer:
32
+ """
33
+ Assembles synthetic bench datasets by config.
34
+
35
+ Config dict keys (all optional, default to paper baseline):
36
+ slow_and_low_2: int — number of 2-session slow_and_low scenarios
37
+ slow_and_low_4: int
38
+ slow_and_low_8: int
39
+ fanout_3: int — fanout with 3 containers
40
+ fanout_5: int
41
+ fanout_10: int
42
+ distributed_staging: int
43
+ benign_narrow: int
44
+ benign_broad_etl: int — split equally between broad and etl profiles
45
+ benign_false_taint: int
46
+ seed: int — RNG seed (default: 42)
47
+ """
48
+
49
+ def __init__(self, pool: TopologyPool | None = None) -> None:
50
+ self._pool = pool or TopologyPool()
51
+
52
+ def compose(self, config: dict[str, Any] | None = None) -> list[Scenario]:
53
+ """
54
+ Compose a dataset from config.
55
+
56
+ Returns list of Scenario objects sorted by scenario_id.
57
+ """
58
+ cfg = dict(_PAPER_BASELINE_COUNTS)
59
+ if config:
60
+ cfg.update(config)
61
+
62
+ seed = int(cfg.get("seed", 42))
63
+ rng = random.Random(seed)
64
+
65
+ scenarios: list[Scenario] = []
66
+
67
+ def _topo(i: int):
68
+ return self._pool.get(i % len(self._pool))
69
+
70
+ # slow_and_low variants
71
+ for n, key in [(2, "slow_and_low_2"), (4, "slow_and_low_4"), (8, "slow_and_low_8")]:
72
+ count = int(cfg.get(key, 0))
73
+ for i in range(count):
74
+ s = atk.slow_and_low(
75
+ atk.SlowAndLowConfig(staging_sessions=n),
76
+ _topo(i),
77
+ scenario_id=f"{key}_{i:04d}",
78
+ rng=rng,
79
+ )
80
+ scenarios.append(s)
81
+
82
+ # fanout variants
83
+ for n, key in [(3, "fanout_3"), (5, "fanout_5"), (10, "fanout_10")]:
84
+ count = int(cfg.get(key, 0))
85
+ for i in range(count):
86
+ s = atk.fanout(
87
+ atk.FanoutConfig(n_containers=n, agent_profile="narrow"),
88
+ _topo(i),
89
+ scenario_id=f"{key}_{i:04d}",
90
+ rng=rng,
91
+ )
92
+ scenarios.append(s)
93
+
94
+ # distributed staging
95
+ dist_count = int(cfg.get("distributed_staging", 0))
96
+ for i in range(dist_count):
97
+ s = atk.distributed_staging(
98
+ atk.DistributedStagingConfig(),
99
+ _topo(i),
100
+ scenario_id=f"dist_{i:04d}",
101
+ rng=rng,
102
+ )
103
+ scenarios.append(s)
104
+
105
+ # benign narrow
106
+ bn_count = int(cfg.get("benign_narrow", 0))
107
+ for i in range(bn_count):
108
+ s = ben.benign_narrow(
109
+ _topo(i),
110
+ scenario_id=f"benign_narrow_{i:04d}",
111
+ rng=rng,
112
+ )
113
+ scenarios.append(s)
114
+
115
+ # benign broad/etl (split equally)
116
+ be_count = int(cfg.get("benign_broad_etl", 0))
117
+ for i in range(be_count):
118
+ profile = "etl" if i % 2 == 0 else "broad"
119
+ s = ben.benign_fanout_like(
120
+ _topo(i),
121
+ agent_profile=profile,
122
+ scenario_id=f"benign_fanout_{profile}_{i:04d}",
123
+ rng=rng,
124
+ )
125
+ scenarios.append(s)
126
+
127
+ # benign false taint
128
+ ft_count = int(cfg.get("benign_false_taint", 0))
129
+ for i in range(ft_count):
130
+ s = ben.benign_false_taint(
131
+ _topo(i),
132
+ scenario_id=f"benign_false_taint_{i:04d}",
133
+ rng=rng,
134
+ )
135
+ scenarios.append(s)
136
+
137
+ return scenarios
138
+
139
+ @classmethod
140
+ def compose_from_yaml(
141
+ cls,
142
+ path: Path | str,
143
+ pool: TopologyPool | None = None,
144
+ ) -> list[Scenario]:
145
+ """
146
+ Load composition config from a YAML file and return the dataset.
147
+
148
+ Requires ``pyyaml`` (``pip install pyyaml``). The bundled config is at
149
+ ``axor_sentinel/bench/configs/paper_baseline.yaml``.
150
+
151
+ Example::
152
+
153
+ from pathlib import Path
154
+ from axor_sentinel.bench.dataset.composer import DatasetComposer
155
+
156
+ scenarios = DatasetComposer.compose_from_yaml(
157
+ Path("axor_sentinel/bench/configs/paper_baseline.yaml")
158
+ )
159
+
160
+ Args:
161
+ path: path to a YAML file with the same keys as _PAPER_BASELINE_COUNTS.
162
+ pool: optional pre-built TopologyPool (uses default pool if None).
163
+
164
+ Raises:
165
+ ImportError: if pyyaml is not installed.
166
+ """
167
+ try:
168
+ import yaml # type: ignore[import-untyped]
169
+ except ImportError as exc:
170
+ raise ImportError(
171
+ "pyyaml is required to load YAML configs: pip install pyyaml"
172
+ ) from exc
173
+ with open(path, encoding="utf-8") as fh:
174
+ config: dict[str, Any] = yaml.safe_load(fh)
175
+ return cls(pool=pool).compose(config=config)