system-auditor

Evidence-based system audits across several machines — with meta bundling.

Deutsche Fassung: README_de.md

---

Quick Navigation

1. Overview
2. Key Capabilities & Core Value Proposition
3. Target Personas & Discoverability
4. Comparative Matrix vs. Alternatives
5. Governance & Runtime Invariants
6. Architecture & System Flow
7. The Three Stages & Outbound Handover
8. Four Tokens & Discrete Windows
9. The Aggregation Ladder
10. One Current Answer Per Window
11. Write-Guard Race Protection
12. End-to-End Audit Lifecycle
13. Sibling Tools & Ecosystem Matrix
14. Installation & CLI Usage
15. Configuration & Public Handover Contract
16. Security, Privacy & Level 1 SBOM
17. Development & Verification Gates
18. License, Maintainers & Starters

---

1. Overview

The auditor examines a composed system in three directions:

1. Rule compliance: Does an observed system state violate a declared policy or convention?
2. Integration (classes I1–I7): Do software modules, manifests, bundles, and bindings collaborate in practice as declared?
3. Governance consistency (classes K1–K4): Are control files, registries, policies, and past architectural decisions consistent with each other?

The guiding principle is convergence: every finding ends with a clear direction — adapt reality to the rule (a concrete measure) or adapt the rule to reality (a decision proposal).

Two machines auditing the same domain do not produce the same result. That is not a defect — it is the most useful thing about running audits across multiple systems.

A Measured Example

Finding: "Gardener governance hardcodes the laptop home path" — AGENTS.md points at C:\Users\alice\….

On WORKSTATION-LG this is real: the path does not exist there. On the laptop the very same line is correct and produces no finding at all.

A single machine can only ever see one half of that reality. Comparing the valid audits of all participating systems yields an evidence-based classification no single run can produce:

Class	Meaning	Impact
systemwide	Every participant found it	Genuine systemwide defect or broken invariant
host_specific	Some found it, others verified clean	Configuration drift or host divergence
inverse	A defect on host A, explicitly fine on host B	Host dependency (e.g. hardcoded path)
divergent	Same location, different rules broken	Differing sync state or conflicting policy reading
unverifiable	A participant never inspected that location	Honest absence of proof (prevents false drift claims)

Note

unverifiable is the honest rung. Without it, every gap in a participant's test coverage would silently masquerade as a real divergence between systems.

---

2. Key Capabilities & Core Value Proposition

• Multi-Host Aggregation Ladder: Seamless aggregation of individual audits into causal verdicts without requiring distributed consensus daemons or centralized databases.
• Model-Manual Interrater Intelligence: Compare verdicts across differing AI models (e.g., Claude, Gemini, GPT) holding system and domain constant to uncover cognitive rater biases and ambiguities.
• Zero Runtime Dependencies: Pure Python standard library implementation (dependencies = []). Zero external wheels required at runtime.
• 100% Local-First & Zero-Egress: Operates in complete air-gapped isolation with zero outbound network calls, telemetry, or cloud tracking.
• Write-Guard Concurrency Defense: Concurrent audits across machines never conflict; pre-write disk inspection safely avoids redundant rewrites when a superset exists.
• Deterministic Discrete Windows: Replace fragile sliding window calculations with deterministic calendar window tokens derived directly from system clocks.
• Convergence Handover Pipeline: Direct decoupled handover to ticket queues (measures) or governance files (decision proposals) via clean CLI argument contracts.

---

3. Target Personas & Discoverability

system-auditor addresses key engineering and governance personas operating complex multi-environment systems:

Persona	Primary Challenge	How system-auditor Resolves It
Multi-Agent Fleet Operators	Auditing autonomous agent fleets across multiple hosts without distributed consensus locks	Derives discrete window tokens and aggregates evidence without distributed locking daemons
System & DevOps Architects	Detecting silent configuration drift and hardcoded host assumptions across workstations and laptops	Classifies cross-machine findings into systemwide, host_specific, inverse, and unverifiable
Open-Source Maintainers	Enforcing strict rule compliance, license integrity, and SBOM hygiene across multiple repos	Zero-runtime-dependency CLI with automated domain discovery and Level 1 SBOM verification
Local-First & Privacy Engineers	Ensuring zero telemetry, zero cloud egress, and user-mode execution boundaries	Guaranteed zero-egress architecture verified by automated AST static analysis gates

---

4. Comparative Matrix vs. Alternatives

Feature / Dimension	system-auditor	osquery	Lynis	Chef InSpec	OpenSCAP
Primary Architecture	Local-First / Multi-Host Meta Bundling	SQL OS Instrumentation	Shell Security Scanner	Ruby Infrastructure Testing	SCAP Compliance Engine
Runtime Dependencies	Zero (Python Standard Library)	C++ Runtime & Binaries	Bash / POSIX Shell	Full Ruby Runtime & Gems	C Libraries & Python Bindings
Cross-Host Aggregation	Native Aggregation Ladder	Central Fleet Server Required	Central Enterprise Server	Chef Automate Server	Satellite / Central Manager
AI Interrater Variance	Built-in (auditor Token)	Not Supported	Not Supported	Not Supported	Not Supported
Privilege Requirement	Unprivileged (RunAsInvoker)	Root / Administrator Required	Root Preferred / Required	Root / SSH Privileged	Root / Privileged Agent
Concurrency Model	Write-Guard Superset Check (Zero Locks)	File Lock / OS Daemon	Sequential Execution	Sequential Runner	Single Process Lock
Coverage Transparency	Honest unverifiable Classification	Silent Missing Rows	Warning / Skip Count	Skipped Control Block	Unchecked Rule State
Convergence Routing	Bilateral (Measure vs Decision)	Query Output Stream	Unilateral Remediation	Failure Exit Code	XML / HTML Report
Network Egress	Strict Zero-Egress by Design	Optional TLS Streaming	Optional Update Checks	Remote WinRM / SSH	Remote Repository Sync

---

5. Governance & Runtime Invariants

Invariant / Capability	Guarantee	Verification & Technical Implementation
1. 100% Local-First & Zero-Egress	Zero telemetry, analytics, remote HTTP requests, or external data leaks	Offline execution via standard library; verified by AST import scan in test_offline_and_zero_egress_invariants
2. Unprivileged Non-Elevation	Strict user-mode execution; no administrator/root escalation or system modifications	Safe execution boundaries; zero privilege elevation requirements (RunAsInvoker)
3. Deterministic Classification	Identical inputs produce bit-for-bit identical multi-host audit verdicts	Canonical sorting of findings and inputs prior to aggregation in system_auditor.meta
4. Identifiability Guard	Invariant that aggregations with >1 varying dimension cannot emit causal verdicts	Strict dimension arity validation in Aggregation class constructor
5. Write-Guard Race Protection	Safe concurrent runs across machines without centralized lock daemons	Pre-write disk re-read in write_meta; skips overwrite if on-disk report is already a superset
6. Discrete Window Tokens	Deterministic temporal alignment without distributed consensus protocols	Config-driven calendar window calculation (system_auditor.tokens) derived directly from clock
7. One Current Answer Per Window	Single authoritative multi-host answer per window, avoiding stale duplicate reports	Window-level rewriting of meta reports; historical versions preserve themselves via window tokens
8. Coverage Transparency Floor	Honest absence-of-proof prevents uninspected paths from masquerading as divergence	unverifiable classification tier tracks verified presence, absence, and unvisited sinks
9. Multi-Host & Lock Hardening	Immune to cloud-sync conflict files and multi-agent lock contamination	Hardened .gitignore ignoring *-conflict-*, *.sync-temp-*, and LOCK.* tokens
10. 48h Security & 5-Day Triage SLA	Committed vulnerability disclosure response and transparent patch lifecycle	Documented SLA in SECURITY.md, coordinated triage within 5 business days via security@open-bricks.org

---

6. Architecture & System Flow

flowchart TD
    subgraph S1["1. Inspection & Discovery"]
        A1["Domain Target / Codebase"] --> D1["discover() Sinks & Manifests"]
        D1 --> M1["Manifests & Policies\nellmos-module.v2 / bundle.v1 / AGENTS.md"]
    end

    subgraph S2["2. Multi-Host Audit Generation"]
        M1 --> R1["Host 1 Audit Run\n(time, domain, sys1, modelA)"]
        M1 --> R2["Host 2 Audit Run\n(time, domain, sys2, modelB)"]
        R1 --> P1["templates/AUDIT-REPORT\nSingle Markdown Reports"]
        R2 --> P1
    end

    subgraph S3["3. Aggregation Ladder & Meta Bundling"]
        P1 --> G1["shared reports_dir\n(Sync Treffpunkt)"]
        G1 --> AP["Aggregation Engine\n(interrater | cross-system | cross-domain | timeseries)"]
        AP --> CL["Classification Core\nsystemwide | host_specific | inverse | divergent | unverifiable"]
    end

    subgraph S4["4. Write-Guard & Convergence"]
        CL --> WG{"write_meta\nWrite-Guard Check"}
        WG -->|"Disk has Superset"| SK["Skip Overwrite\n(Zero Race Conditions)"]
        WG -->|"Fresh Evidence"| MR["Atomic Meta-Report\n(templates/META-REPORT)"]
        MR --> AC["Convergence Direction\nMeasure vs. Decision Proposal"]
    end

    style S1 fill:#f8fafc,stroke:#64748b,stroke-width:1px
    style S2 fill:#f0fdf4,stroke:#22c55e,stroke-width:1px
    style S3 fill:#eff6ff,stroke:#3b82f6,stroke-width:1px
    style S4 fill:#fdf4ff,stroke:#a855f7,stroke-width:1px

Loading

ASCII Architectural Topology (Four-View Projection)

========================================================================================
                      system-auditor: Four-View Architectural Topology
========================================================================================

[VIEW 1: CALLER RUNTIMES, AGENT CLIENTS & CLI ENTRYPOINTS]
  +----------------------------------------------------------------------------------+
  | Caller Ingestion & Execution Interfaces                                          |
  | - CLI Dispatch: 'system-auditor run | list | meta | sweep | export'              |
  | - Autonomous Agent Automation: Antigravity sidecars, Claude, Codex, Kimi-Code    |
  | - Parameter Intake: --domain, --system, --auditor, --window-token, --reports-dir |
  | - Shell Injection Guard: argv array isolation; 100% unprivileged user mode       |
  +----------------------------------------------------------------------------------+
                                           |
                                           | (system_auditor.cli -> engine dispatch)
                                           v
[VIEW 2: SYSTEM-AUDITOR SOVEREIGN ENGINE & AGGREGATION LADDER]
  +----------------------------------------------------------------------------------+
  | Inspection, Verification & Causal Classification Core                            |
  | - Rule & Integration Scanners: policy compliance (K1-K4), binding checks (I1-I7) |
  | - Multi-Host Aggregation Ladder: interrater | cross-system | cross-domain | series|
  | - Identifiability Guard: prohibits causal claims when >1 dimension varies        |
  | - Classification Engine: systemwide | host_specific | inverse | unverifiable     |
  +----------------------------------------------------------------------------------+
                                           |
                                           | (audit rendering / write_report / write_meta)
                                           v
[VIEW 3: RUNTIME PERSISTENCE, EVIDENCE LEDGERS & WRITE-GUARD DEFENSE]
  +----------------------------------------------------------------------------------+
  | Treffpunkt File Storage & Convergence Routing                                    |
  | - Audit Reports: reports_dir/AUDIT-YYYYMMDD--<domain>.<host>.<auditor>-<hash>.md |
  | - Discrete Window Meta: reports_dir/META-YYYYMMDD--<domain>.<scope>-<hash>.md    |
  | - Write-Guard Concurrency Defense: re-reads disk; suppresses overwrite on superset|
  | - Convergence Handover: tickets to queue (measures) & proposals to governance    |
  +----------------------------------------------------------------------------------+
                                           |
                                           | (air-gap isolation perimeter)
                                           v
[VIEW 4: AIR-GAP DEFENSE PERIMETER, RUNASINVOKER & ZERO-EGRESS BOUNDARY]
  +----------------------------------------------------------------------------------+
  | Security, Privacy & Runtime Isolation Invariants                                 |
  | - RunAsInvoker Non-Elevation: strictly unprivileged user-mode execution          |
  | - 100% Local-First & Zero Egress: 0 network sockets, 0 HTTP, 0 outbound telemetry|
  | - Zero External Dependencies: 100% Python Standard Library (dependencies = [])   |
  | - Level 1 SBOM Invariants: INV-LOCAL-01..INV-SLA-10 cryptographically verified   |
  +----------------------------------------------------------------------------------+
========================================================================================

---

7. The Three Stages & Outbound Handover

map      what is there            ->  system-explorer   (optional)
verdict  what is wrong about it   ->  system-auditor    (this module)
measure  what we do about it      ->  ticket system     (optional)

A map is value-free; a ticket is an action. In between sits the judgment: which rule is violated, what do we recommend, and is the rule itself still right?

Nothing here requires its neighbours. Detected, they are used; absent, the auditor reads directly and writes files. Same pattern in every direction: know them, don't need them.

sequenceDiagram
    autonumber
    participant Explorer as "system-explorer (Map)"
    participant Auditor as "system-auditor (Verdict)"
    participant Sink as "Handover Sink (Measure)"
    participant Gov as "Governance & Maintainer (Decision)"

    Explorer->>Auditor: "Observed system state and manifest inventory"
    Note over Auditor: Evaluates Compliance, Integration (I1-I7) & Governance (K1-K4)
    alt Reality violates valid rule
        Auditor->>Sink: "Emit Measure Ticket (--title and --body)"
        Sink-->>Auditor: "Ticket registered (Adapt reality to rule)"
    else Rule is obsolete or conflicting
        Auditor->>Gov: "Emit Decision Proposal (TO-DECIDE-USER)"
        Gov-->>Auditor: "Policy updated (Adapt rule to reality)"
    end

Loading

---

8. Four Tokens & Discrete Windows

Every audit answers four questions, and each answer is an immutable token:

Token	Question	Description
time	When?	The discrete period window this statement belongs to (e.g. 20260817)
domain	What?	The domain that was audited (e.g. bundles, skills, mcp)
system	Where?	The machine name or environment inspected (e.g. WORKSTATION-LG)
auditor	Who?	The model or agent identity that conducted the audit (e.g. claude-3-5-sonnet)

Why Discrete Windows Instead of Sliding Spans

A sliding window ("valid for 14 days from run") makes overlap a matter of degree — every machine has to compare pairs to resolve status. A window grid derived from configuration turns that into a direct lookup: ask the clock, get a token. Two machines that never talk to each other derive the same token for the same moment, turning "same period" into a fast string comparison instead of a distributed consensus problem.

---

9. The Aggregation Ladder

Hold some tokens fixed, let the rest vary. An aggregation may only attribute a cause when exactly one dimension varies — otherwise a difference is mathematically unidentifiable. This rule is enforced in the constructor.

Aggregation	Fixed Dimensions	Varying Dimension	What It Identifies
interrater	time + domain + system	auditor	Do two AI models agree on the same machine?
cross-system-rater	time + domain + auditor	system	A clean, controlled host effect
cross-system	time + domain	system	Machine variance (model uncontrolled; practical)
cross-domain	time + system + auditor	domain	Is the same rule violated across distinct domains?
timeseries	system + domain	time	How did this domain develop over consecutive windows?
timeseries-rater	system + domain + auditor	time	Domain trajectory through the lens of one model
full-system	time + system	domain + auditor	Descriptive only — inventory (build_inventory), no verdict

---

10. One Current Answer Per Window

system A audits `bundles`   ->  single audit
system B audits `bundles`   ->  meta-2  (created)
system C audits `bundles`   ->  meta-3  (same file, rewritten)

Within a window the meta-audit is overwritten, not archived: "what do we know about this domain in this window" has one current authoritative answer. Keeping meta-2 beside meta-3 would leave conflicting answers to the same question.

History keeps itself. The previous window has a different time token, hence a different filename, and stays untouched.

---

11. Write-Guard Race Protection

Parallel audits of one domain are the premise of a meta-audit, not a collision. There is nothing to exclude, so this module holds no distributed locks.

• The audit itself is read-only. Nothing in the audited domain is modified.
• The classification is deterministic. Same inputs yield identical markdown outputs.
• Write-Guard verification: write_meta re-reads the destination on disk. If the file on disk already rests on a superset of the planned inputs (e.g. written by a faster concurrent run), it safely skips rewriting.

---

12. End-to-End Audit Lifecycle

sequenceDiagram
    autonumber
    participant Dev as Auditor / Agent
    participant CLI as system-auditor CLI
    participant Disk as Local / Shared reports_dir
    participant Engine as Meta Aggregator

    Dev->>CLI: system-auditor time-token
    CLI-->>Dev: Returns current Window Token (e.g. 20260817)

    Dev->>CLI: system-auditor next-domain --domains "bundles,skills,mcp"
    CLI-->>Dev: Selects least recently audited domain

    Dev->>CLI: system-auditor discover --domain-path /path/to/domain
    CLI-->>Dev: Lists manifests, rules, and policy sinks

    Note over Dev: Auditor conducts inspection (Rules, Integration I1-I7, Governance K1-K4)
    Dev->>Disk: Write Single Audit (AUDIT-BERICHT.de.md / AUDIT-REPORT.en.md)

    Dev->>CLI: system-auditor meta-plan --reports ./reports --aggregation cross-system
    CLI->>Disk: Scans foreign single reports for matching window

    alt Meta Audit Due (New Foreign Inputs Found)
        CLI-->>Dev: Plan Action: CREATE / UPDATE
        Dev->>Engine: build_meta(runs, aggregation)
        Engine->>Engine: Classify (systemwide, host_specific, inverse, divergent, unverifiable)
        Engine->>Disk: write_meta (Verifies disk superset before atomic write)
        Disk-->>Dev: Meta-Report Published
    else Up to Date
        CLI-->>Dev: Plan Action: SKIP (Superset already on disk)
    end

Loading

---

13. Sibling Tools & Ecosystem Matrix

system-auditor is part of the ellmos-ai ecosystem under the open-bricks umbrella:

Repository	Focus	Integration Role with system-auditor
ellmos-ai/system-explorer	System Mapping	Provides structured inventory maps ("what is there")
ellmos-ai/system-auditor	Audit & Verdict	Evaluates compliance, integration, and governance consistency
ellmos-ai/ellmos-controlcenter-mcp	MCP Control Plane	Context packing, tool routing, and capability discovery
ellmos-ai/ellmos-delegation-authority	Cryptographic Authority	Nonce-based cryptographic delegation grants
ellmos-ai/sqlite-transit-sync	Database Transit	Zero-egress WAL-checkpointed SQLite replication
ellmos-ai/ellmos-voice-io	Voice Interface	Zero-egress local speech synthesis and audio telemetry
ellmos-ai/memoryhooker-provenance	Provenance Tracking	Cryptographic evidence hashes and audit trail validation
ellmos-ai/workflowhooker-provenance	Workflow Attestation	Immutable execution logs and cross-system workflow verification
dev-bricks/automation-master	Task Automation	Orchestrates automated batch maintenance workflows
dev-bricks/automizer-for-claude-desktop	Process Discrimination	Atomic configuration snapshots & safe execution queues
dev-bricks/WikiStub-Seed	Documentation Seeding	Structural wiki generation and documentation scaffolding
file-bricks/ProSync	Local Backup	Safe multi-profile sync and SQLite WAL checkpoint protection
doc-bricks/CleanMarkdown	Document AST	High-fidelity Markdown AST validation and clean rendering
assistassets-ai/PrivacyMailDesk	Local Privacy Mail	Zero-egress mail evaluation and attachment hygiene
research-line/prompt-archaeology-casestudy2	Prompt Archaeology	Scientific methodology and empirical prompt evolution logs
open-bricks/open-bricks	Umbrella Organization	Common architecture standards, governance, and licensing

---

14. Installation & CLI Usage

# Editable install
python -m pip install -e .

# Display active configuration and resolved reports directory
system-auditor config

# Query current discrete time window token
system-auditor time-token

# Determine the next due domain in rotation
system-auditor next-domain --domains "bundles,skills,mcp" --reports ./reports --system $HOSTNAME

# Discover conventions, manifests, and policy sinks for a domain
system-auditor discover --domain-path /path/to/domain

# Plan pending meta-audits in current window
system-auditor meta-plan --reports ./reports --aggregation cross-system
system-auditor meta-plan --reports ./reports --aggregation interrater

# Identify single audits belonging to previous windows
system-auditor stale --reports ./reports --system $HOSTNAME

# Deterministic catalog-to-Pages check for the pages-drift example domain
system-auditor --json pages-drift \
  --modules-catalog "<HOME>/OneDrive/.TOPICS/.AI/.MODULES/modules.catalog.json" \
  --skills-registry "<HOME>/OneDrive/.TOPICS/.AI/.SKILLS/registry/components.json" \
  --bundles-catalog "<HOME>/OneDrive/.TOPICS/.AI/.BUNDLES/bundles.catalog.v1.json" \
  --site-dir "C:/_Local_DEV/repos/ellmos-ai.github.io"

pages-drift returns exit 0 without drift, exit 1 for evidenced mismatches, and exit 2 for incomplete or unreadable inputs. It compares the three catalog counts and public module IDs, and enforces that a recipe released on bundles.html cannot name a non-public module. The domain is added to the example configuration only; no host-local live configuration is invented.

---

15. Configuration & Public Handover Contract

cp config/system-auditor.config.example.json system-auditor.config.json
system-auditor config          # shows resolved config

Config lookup order: --config, SYSTEM_AUDITOR_CONFIG, ./, ./config/, ~/.system-auditor/.

{
  "time_grid": {
    "unit": "weeks",
    "step": 1,
    "anchor": "2026-01-05"
  },
  "reports_dir": "./reports",
  "policy": {
    "cross-system": "always",
    "interrater": "always",
    "cross-domain": "on-demand"
  }
}

Where findings go: the public handover contract

The auditor knows exactly one outbound interface. It appends --title <title> --body <text> to whatever command the sink was configured with, and knows nothing about ticket formats, lifecycle folders, categories or model routing — that stays the ticket system's business, so both sides can improve independently.

{
  "sink": {
    "kind": "command",
    "target": "python <path>/ticket-master/bin/ticket_master.py --intake --tickets-dir <queue>",
    "enabled_probe": "python <path>/ticket-master/bin/ticket_master.py --list"
  }
}

Configure the command prefix only — the sink appends --title/--body itself. The consumer side of this contract is documented in ticket-master's README under "The public producer contract". Its --intake accepts the description either positionally or via --body; before 2026-09-12 it took only the positional form, so this public call went nowhere and only ticket-master's internal lib/ticket_writer.py wiring worked (measure M-20260820-auditor-ticket-sink).

If no ticket system is installed, the probe fails, or the command errors, findings are written as files instead. Nothing is lost, only the routing — an absent ticket system is a normal state, not an error.

Important

reports_dir is the multi-host meeting point. It must reside in a cloud-synchronized folder shared across participating machines. In a host-local directory, meta-audits cannot aggregate foreign reports.

---

16. Security, Privacy & Level 1 SBOM

system-auditor is built with a strict Local-First & Zero-Egress model. It contains zero telemetry, requires zero network connectivity, operates with unprivileged user permissions, and employs deterministic write-guards.

The project maintains a certified Level 1 SBOM inventory in THIRD_PARTY_LICENSES.md validating all 10 governance invariants (INV-LOCAL-01 through INV-SLA-10), and provides full attribution in NOTICE.

For full details, supported versions, and vulnerability disclosure contacts, see SECURITY.md.

---

17. Development & Verification Gates

# Run pytest test suite (including metadata contract tests)
python -m pytest -q

# Run Ruff linter
ruff check src tests

# Verify bytecode compilation
python -m compileall -q src tests

---

18. License, Maintainers & Starters

MIT — see LICENSE, NOTICE, and THIRD_PARTY_LICENSES.md.

Starters

This module ships the provider-neutral role starters START.bat and start.sh in the repository root. They are generated from roles[] in ellmos-module.v2.json by COMA (python -m coma starters generate --manifest ellmos-module.v2.json --output-dir .), so they are regenerated rather than hand-edited. Each starter prefers the unified-gui console and falls back to COMA, which asks for provider, model and reasoning effort at start.

There are deliberately no provider-specific starters under bin/providers/ here, unlike ticket-master: the auditor has no hand-written dispatcher of its own, so a per-provider file would only duplicate argv knowledge that COMA already owns. Starting the auditor through a task role (taskplan launch --label system-auditor) remains equally valid and uses the same declaration. Decided in ticket T-20260906-249053451.