EHMA — Epistemic Hygiene for Machine Actors

A reproducible audit methodology for AI-agent credentials.

AI agents authenticate into enterprise systems using credentials that were never designed for non-human actors — long-lived keys, shared .env files, and copied credential bundles scattered across the filesystem. Unlike human accounts (governed by centralized login controls and review cycles), machine credentials typically have no comparable governance layer. Yet these agents can reach external systems with broad authority, often beyond the human who configured them.

This repository contributes a reproducible audit methodology for measuring and remediating credential sprawl in environments that host AI agents.

---

What it measures

Four primary metrics, all computed by read-only scanners:

Metric	What it captures
Access-pair blast-radius	Σ over files of readers × keys. Owner-only = 1 reader, world-readable = WORLD_CAP (100). Template files excluded.
Sprawl ratio	Duplicate keys / unique keys. Proxy for rotation complexity.
Manifest coverage	% of high-value keys sourced from a single source-of-truth vault.
Git exposure	Files containing real secrets that are tracked by any git repository.

Template files (.env.example, .sample, .template, .dist) are categorized separately — they document shape, not secrets, and are excluded from the blast-radius calculation by design.

---

Scripts

Script	Purpose	Default safety
scripts/credential_audit.py	Read-only scanner; produces JSON + Markdown reports	Read-only by definition
scripts/credential_cleanup.py	Staged remediation: RETIRE (archive), CHMOD (tighten perms), FLAG (human review)	Dry-run; requires --apply
scripts/reprocess_baseline.py	Derive a pre-cleanup baseline from intervention log + post-scan	Pure derivation

All mutations are reversible (archive, not delete). All secret values are read but never written to reports — only variable names.

---

Quick start

# 1. Scan a filesystem root (read-only)
python3 scripts/credential_audit.py --root /path/to/your/root

# 2. Preview remediation (dry-run is the default)
python3 scripts/credential_cleanup.py --root /path/to/your/root

# 3. Apply remediation (archives + chmods)
python3 scripts/credential_cleanup.py --root /path/to/your/root --apply

# 4. Re-scan to capture post-cleanup state
python3 scripts/credential_audit.py --root /path/to/your/root --label t1_post_cleanup

# 5. Reconstruct the t0 baseline from the intervention log
python3 scripts/reprocess_baseline.py \
  --input reports/credential_hygiene/<latest>.json \
  --intervention reports/credential_hygiene/cleanup_<ts>.json \
  --json-out reports/credential_hygiene/t0_baseline.json \
  --md-out reports/credential_hygiene/t0_baseline.md

---

Manifest-driven secret sync

This repository documents — but does not bundle — a reference manifest format for driving generated .env distribution. See:

• schemas/secret_sync.schema.json — JSON Schema for the manifest
• examples/secret_sync.example.json — anonymized example
• docs/methodology.md — full metric definitions
• docs/case_study_reference_lab.md — n=1 validation with real numbers

The reference implementation assumes a generic secret source accessed by CLI or environment injection. The methodology is backend-agnostic as long as the generated files follow the same manifest shape.

---

Case study (n=1)

A validated n=1 case study from a reference lab:

	t₀ (reconstructed)	t₁ (post-cleanup)
Real-secret files	20	17
Unique secret keys	92	78
World-readable real-secret files	5	0
Access-pair blast-radius	1,869	67
Manifest coverage	—	100% (27/27 keys)

Net: 96.4% reduction in access-pair blast-radius.

Full artifacts (baseline JSON, post-cleanup JSON, intervention log) are published on OSF: https://osf.io/8nrd3/ (EHMA case-study archive).

---

Waitlist

If you want to run this methodology against your own lab and contribute anonymized t₀/t₁ results to a comparative v2 study:

→ Open a GitHub issue with the "waitlist" label.

Minimum disclosure for participation: file count, tier distribution, access-pair count, manifest coverage %. Optional: remediation timeline, tooling stack. No secret values are ever requested or stored.

---

Citation

Ayala, J. (2026). Epistemic Hygiene for Machine Actors: A Reproducible Audit Methodology for AI Agent Credentials. OSF: https://osf.io/8nrd3/

---

Scope & limits

This catches: filesystem credential sprawl, world-readable secrets, duplicate keys across files, git-tracked secret files, missing vault coverage.

This does not catch: in-memory secrets, externally managed secrets that never touch disk, secrets embedded in container images, secrets injected at runtime by orchestrators, secrets stored in browser extensions or agent state files that aren't .env-shaped.

See docs/threat_model.md for the full scope discussion.

---

Related work

This is a first applied artifact in a broader epistemic-provenance research direction for AI agents. Credential hygiene is a narrow slice of the larger question: how do we know why a machine actor holds the authority it holds, and can we audit that?

• EHMA archive: https://osf.io/8nrd3/
• Parent research project: https://osf.io/bvy3q/
• Contact: open a GitHub issue on this repository