HarvestGuard

Open-source, local-first cryptographic asset inventory and evidence collection for technology diligence and post-quantum migration planning.

Built by Timothy Serewicz. Executive Technology Advisor & Fractional CTO.

HarvestGuard helps teams answer three practical questions: what cryptographic assets are present, where were they observed, and what evidence supports each finding? It keeps observed facts separate from inference and leaves risk, readiness, and remediation decisions to qualified human review.

Quickstart

Evaluating HarvestGuard for the first time takes seven steps, in order:

1. Install the CLI
2. Verify the installation
3. Scan an authorized local path
4. Try the safe repository demo
5. Review sample evidence output
6. Validate on your own Linux host
7. Read the claims boundary

1. Install the CLI

Python 3.10 or newer is required. pipx gives the CLI its own environment, which is what you want for ordinary command-line use, because HarvestGuard pulls in Semgrep and three cloud SDKs:

pipx install harvestguard

Plain pip works too, from a clean virtual environment — the recommended form for validation and development workflows, and the one the rest of this Quickstart assumes when it installs from a repository checkout:

python3 -m venv venv            # macOS: python3.12 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
python -m pip install harvestguard

Debian and Ubuntu: error: externally-managed-environment. Newer releases enforce PEP 668 and refuse a system-wide pip install, reporting:

error: externally-managed-environment

That is the distribution protecting its own Python. Install pipx rather than overriding it — do not force a system-wide install with --break-system-packages:

sudo apt update
sudo apt install -y pipx
pipx install harvestguard

2. Verify the installation

harvestguard --version

If the shell reports that harvestguard is not found even though the install succeeded, the pipx binary directory is not on your PATH. On a root test host, either run the executable directly:

/root/.local/bin/harvestguard --version

or put the directory on PATH first:

export PATH="$PATH:/root/.local/bin"
harvestguard --version

For a non-root user, the executable is commonly at:

~/.local/bin/harvestguard

3. Scan an authorized local path

harvestguard scan /path/to/project --type all --summary

That prints the evidence summary for a path you choose. Scan only targets you are authorized to scan.

4. Try the safe repository demo

The demo corpus is repository content, not part of the PyPI package — it does not exist after pip install harvestguard. To run it, clone the repository and install from that checkout:

git clone https://github.com/serewicz/HarvestGuard.git
cd HarvestGuard
python3 -m venv venv            # macOS: python3.12 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
python -m pip install .

harvestguard scan demo/sample_target --type all --summary

5. Review sample evidence output

Run, review, and export a local scan of the repository's deliberately synthetic demo target — this is the canonical first-run sequence, and it assumes the clone-and-install above:

# 1. Review the scan in the terminal
harvestguard scan demo/sample_target --type all --summary

# 2. Export the same scan as evidence artifacts (two runs; --json and
#    --markdown cannot be combined in one command)
harvestguard scan demo/sample_target --type all --json findings.json
harvestguard scan demo/sample_target --type all --markdown report.md

findings.json and report.md are written relative to the directory you run the command in — the repository root, if you followed the steps above. Nothing is uploaded anywhere, and no evidence artifact is written unless you pass a path. A --type all scan does create one scratch directory, harvestguard-semgrep/ under your system temp directory, which the bundled Semgrep code analysis uses for its own settings and cache. It holds no scan output and is created even for --summary.

What to expect from the demo scan:

• all three commands exit 0. Exit 1 means an execution or output failure — a scanner failed partway through, or writing a requested JSON/Markdown file or evidence-store record failed after the scan — and exit 2 means invalid usage. See Exit Codes for the individual cases.
• the summary reports Files scanned: 4 and Total normalized records: 5, and the JSON array holds those same five normalized records.
• Errors: 1 and Findings with finding-level errors: 1 are expected, not a failure. The demo .env fixture deliberately contains a PEM header whose body is fake text, so it is reported as a low-confidence Malformed PEM Private Key record whose errors field names the parse failure. Scanner execution errors: 0, and the exit code stays 0. Read Errors and Warnings and each finding's errors, not just the exit code, before treating a scan as clean — reading coverage from an artifact.
• the Markdown report's Coverage row reads Bounded by configured scan scope, because --max-depth defaults to 3 — a configured bound, not a failure.
• one aggregate filesystem record is host-dependent, so its volume-encryption value and confidence may legitimately differ on your machine, and on a host where volume status cannot be determined at all the Coverage row reads Not complete instead: what varies by host.

The demo contains fake patterns only—never real credentials; demo/sample_target/README.md documents each demo file, its synthetic provenance, and the finding it is expected to produce. To see what that output looks like before installing anything, read the sample JSON and Markdown artifacts from exactly this demo scan in docs/examples/first-run/, and the per-finding walkthrough in the CLI demo walkthrough.

6. Validate on your own Linux host

An operator-driven validation harness ships in the repository checkout from step 4. Run it from the repository root, on a Linux host you control, with harvestguard already installed:

./validation/run-validation.sh --workspace /tmp/hg-validation

The harness generates a bounded corpus of native-tool artifacts, freezes the expectations before scanning, runs the installed harvestguard CLI against the frozen corpus, and reports observations for human review. Each of its eight stages advances only when the operator confirms it, it installs nothing, and it writes only inside the workspace you name.

A bounded dry-run exercises the same eight stages with mock records instead — no native generator and no scanner run, so it makes no cryptographic, scanner, or format-support claim:

./validation/run-validation.sh --dry-run --workspace /tmp/hg-validation-dry-run

A completed run shows how the installed CLI behaved against those generated bytes on that host. It is not proof of complete format support, of every valid variant of a supported format, or of any platform, architecture, scan type, or generator that the run did not exercise.

The stages, safety boundaries, already-validated platforms, and their limitations are documented in validation/README.md. The Phase 1 generator contract — which script produces which format case, with which native tool — is in validation/generators/README.md.

7. Read the claims boundary

This is one small selected synthetic sample. It shows the output shape; it does not demonstrate exhaustive discovery, runtime use, exploitability, business risk, compliance, remediation priority, or quantum readiness.

Each scanner's detection surface is deliberately narrow and none of them is exhaustive, so absence of a finding is not proof of absence. What every scanner supports, what it can miss, and how to read its confidence value are documented in detection characterization; the canonical evidence, confidence, and inference boundaries are in docs/PRODUCT_PRINCIPLES.md.

Windows activation instructions, cloud targets, output formats, exit codes, and the optional local evidence store are covered in the detailed setup and usage section and CLI reference.

PQC readiness starts with inventory

Post-quantum migration planning needs a defensible inventory before teams can reason about dependencies, timelines, or change. HarvestGuard contributes that first layer: bounded observations from supported targets, confidence and coverage limits, and evidence that reviewers can inspect.

It does not measure runtime exposure, crypto-agility, exploitability, or business impact, and it does not determine quantum readiness or prescribe a migration plan. Those conclusions require context and human judgment beyond a local evidence scan.

Supported capabilities at a glance

• local filesystem and cloud-provider encryption metadata inventory;
• category-and-count-only sensitive-data classification;
• bounded Python source analysis for selected weak or legacy crypto usage;
• local cryptographic asset evidence across supported certificate, key, keystore, truststore, encrypted-container, OpenSSH host identity, and Kubernetes TLS Secret manifest formats;
• CLI summary, JSON, and Markdown output, plus an optional local evidence store;
• a separate Streamlit dashboard, including an explicitly experimental HNDL inference that is not emitted in CLI evidence reports.

Coverage is intentionally detector-specific rather than a claim of exhaustive discovery. See Detailed capability coverage and detection characterization for the exact supported evidence, boundaries, and known false-positive and false-negative conditions.

HarvestGuard is licensed under Apache License 2.0, is pre-1.0 and under active development, and welcomes contributions. Please read CONTRIBUTING.md before starting non-trivial work; scoped issue-first changes help keep claims and detector contracts reviewable.

Why HarvestGuard?

HarvestGuard inventories cryptographic assets today, providing evidence organizations can use to assess future migration planning as cryptographic standards evolve.

In M&A due diligence, PE/VC portfolio reviews, acquisition planning, and enterprise technology decisions, teams need defensible evidence about encryption posture, sensitive-data placement, and cryptographic assets before they can assess modernization or migration work.

HarvestGuard gives teams local, evidence-focused visibility into implemented cryptographic posture across supported storage, cloud, source-code, and filesystem targets. Its outputs can contribute to a Technology Due Diligence Evidence Package for technology due diligence, executive assessment, acquisition review, integration planning, and cryptographic modernization planning.

HarvestGuard is additive to tools organizations may already use for security operations, cloud security, asset management, vulnerability management, and governance. It is not a replacement for broad vulnerability-management, CSPM, GRC, SIEM, or security-operations platforms.

What HarvestGuard Does

HarvestGuard collects verifiable cryptographic evidence, communicates confidence and unknowns, surfaces ownership signals, and frames the questions organizations must answer. It does not prescribe the answer.

In practice, HarvestGuard helps reviewers:

• collect observable cryptographic evidence from supported targets;
• keep evidence, inference, uncertainty, and coverage limits visible;
• surface source-attributed ownership signals without assigning business accountability;
• use the resulting evidence in diligence, executive assessment, and post-quantum migration planning.

What HarvestGuard Does Not Do

HarvestGuard does not:

• determine whether an organization is quantum-ready;
• assign business ownership or accountability;
• recommend products, vendors, architectures, or remediation plans;
• estimate migration or remediation costs;
• certify compliance;
• replace security assessments, legal review, architecture review, diligence professionals, or executive judgment.

Each scanner's detection surface is also deliberately narrow, and none of them is exhaustive. Absence of a finding is not proof of absence. What every scanner supports, what it can miss, its likely false positives and false negatives, and how to read its confidence value are documented per scanner in docs/DETECTION_CHARACTERIZATION.md.

See docs/PRODUCT_PRINCIPLES.md for the canonical evidence, confidence, ownership-signal, and recommendation boundaries, and docs/CLAIMS_AUDIT.md for how each claim below is classified — implemented and tested, implemented with known limitations, experimental / Needs Validation, planned, or out of scope.

Target Users & Use Cases

• M&A, IP Lawyers, PE/VC Firms
  Quickly scan target company storage/cloud for encryption status and sensitive-data categories (IP, customer PII), plus an inferred HNDL exposure bucket the dashboard marks as a heuristic needing validation. Many targets have poor inventory—this tool surfaces evidence early.

• Deal Speed & Planning Evidence
  Pre-LOI or during DD, collect cryptographic evidence that can inform integration planning, modernization discussions, and follow-up advisory review.

• Executive Assessment
  Give leaders a clearer evidence base for questions about cryptographic posture, long-lived data exposure, and future migration planning without claiming a complete quantum-readiness assessment.

• Ease of Use
  Free/open-source, self-hosted, or simple web-based assessment → low friction entry.

• Evidence Package (planned — see docs/ROADMAP.md)
  Current JSON and Markdown reports are evidence outputs; future work may package these into a broader Technology Due Diligence Evidence Package for legal, advisory, and executive review.

Executive-facing reporting vision is documented in docs/EXECUTIVE_DELIVERABLES.md. HarvestGuard produces technical evidence first; executive deliverables are derived from that evidence and must remain traceable back to it.

Detailed capability coverage

• Local filesystem — real encryption detection: file-signature checks for common encrypted formats (OpenSSL, PGP/GPG, age, LUKS containers, encrypted ZIP), falling back to volume-level status (FileVault / LUKS / BitLocker) when a file isn't itself a recognized encrypted format. Local scans are bounded by --max-depth, which defaults to 3 — an ordinary scan is not unlimited recursion.

• AWS S3, Google Cloud Storage, Azure Blob Storage — per-object/blob encryption status as reported by each provider's API (S3 ServerSideEncryption, GCS CMEK vs. Google-managed, Azure customer-managed encryption scope vs. Microsoft-managed). This is provider metadata, not independent proof of the underlying cryptographic implementation. Credentials come from each provider SDK's own default resolution; HarvestGuard never manages, prompts for, or stores them.

• Sensitive-data classifier — flags files containing email addresses, SSNs, phone numbers, Luhn-validated payment card numbers, and credentials/secrets (AWS keys, private keys, GitHub/Slack tokens). Reports category and count only, never the matched values, so a scan result can't itself leak the sensitive data it found.

• Crypto code analysis — flags weak/legacy crypto library usage in source (MD5/SHA1, DES/3DES/RC4, ECB mode, sub-2048-bit RSA keys) via a small vendored Semgrep rule set, not Semgrep's hosted registry — local scans stay network-free. Source text only, and the current rules target Python source only: no binary, bytecode, runtime, or network/TLS discovery, and equivalent weak-crypto usage in another language produces no finding today.

• Cryptographic asset inventory — discovers supported local cryptographic asset evidence without decryption, password or passphrase prompting, key recovery, or runtime-use claims. Current coverage includes:

  • X.509 certificates and supported private/public key material;
  • PKCS#12 containers and Java keystore/truststore evidence;
  • OpenSSL, OpenPGP/GPG, age, encrypted PKCS#8, CMS/PKCS#7 EnvelopedData, and legacy encrypted PEM evidence;
  • gocryptfs cipher roots;
  • Mozilla NSS SQL database sets;
  • OpenSSH host identity evidence;
  • Kubernetes TLS Secret manifests.

  Coverage is intentionally detector-specific and not exhaustive. Absence of a finding is not proof of absence. See docs/CRYPTO_INVENTORY.md and docs/DETECTION_CHARACTERIZATION.md for exact supported formats, parser and evidence boundaries, metadata fields, confidence levels, and known false-positive and false-negative conditions.

• Unified CLI — runs local scanners through the normalized finding model with summary, JSON, and Markdown report output. --json emits an array of normalized findings; --markdown emits a local, evidence-only report covering scan context, scanner versions, detailed findings with confidence, unknowns, limitations, errors, and coverage caveats — no risk score, HNDL exposure, remediation advice, business impact, or quantum-readiness conclusion. Reports can contain sensitive identifiers (paths, object and bucket names, ownership signals), so handle the generated files accordingly. See docs/CLI.md.

• HNDL exposure scoring (experimental — Needs Validation) — a heuristic Harvest-Now-Decrypt-Later exposure bucket (High/Medium/Low) and 0–100 risk score inferred from encryption status and path signals. An inference and an ordering aid, not a measured fact, a probability, or a quantum-readiness verdict. It appears in the Streamlit dashboard only — never in CLI JSON or Markdown reports — and is labeled there as inferred and unvalidated. See docs/TERMINOLOGY.md.

• Streamlit dashboard — pie/bar charts and a results table per scan. Run with streamlit run main.py from the repository root: the dashboard is a separate operating path and is deliberately not part of the installed harvestguard CLI package.

Not yet built: CBOM/PDF export and network-level crypto scanning (TLS/cipher-suite detection). See docs/ROADMAP.md for what's next and why, in rough priority order.

Detailed setup and usage

Prerequisites

• Python 3.10 or newer (python3 --version). macOS ships Python 3.9.6 as /usr/bin/python3, which is too old — install a current Python (for example brew install python@3.12) and use that interpreter to create the virtual environment. Do not replace the system Python.
• Elevated rights (sudo) for deep local scans (or IAM for cloud)

Install the CLI

One command from a clean virtual environment installs harvestguard and every dependency it needs — pyproject.toml is authoritative, so there is no second requirements step. For ordinary command-line use pipx install harvestguard works as well, and is the route to take on a Debian or Ubuntu host that enforces PEP 668; see Install the CLI. From PyPI:

python3 -m venv venv            # macOS: python3.12 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
python -m pip install harvestguard
harvestguard --version

The installed distribution contains the CLI and its packaged modules. Neither the wheel nor the source archive contains the demo corpus, the Streamlit dashboard, the test suite, or the documentation tree, so clone the repository to use those resources:

# Clone the repo
git clone https://github.com/serewicz/HarvestGuard.git
cd HarvestGuard

# Create and activate a clean virtual environment
python3 -m venv venv            # macOS: python3.12 -m venv venv
source venv/bin/activate        # On macOS/Linux
# venv\Scripts\activate         # On Windows

# Install the CLI and its dependencies
python -m pip install .

# Confirm it works -- from anywhere, not just this directory
harvestguard --version
cd ~ && harvestguard scan /path/to/target --type filesystem --summary

pip may print long runs of repeated download and "looking at multiple versions of…" messages while resolving the Semgrep/OpenTelemetry dependency graph. That backtracking is normal and can take several minutes on a cold cache; a nonzero exit or a resolution error is a genuine failure.

Contributors who want their edits picked up without reinstalling use python -m pip install -e . instead. See CONTRIBUTING.md for the full dev setup.

More CLI examples

harvestguard scan ./tests/fixtures/crypto_inventory

# Write a Markdown evidence report
harvestguard scan ./tests/fixtures/crypto_inventory --markdown report.md

# Run a single scan type, or a cloud scan (uses provider SDK default creds)
harvestguard scan ./tests/fixtures/crypto_inventory --type crypto --json findings.json
harvestguard scan my-bucket --type s3 --json --quiet

See docs/CLI.md for all scan types, options, and exit codes.

Keeping a local evidence record

Every scan is given a UUID scan ID that all of its findings carry. Scans are ephemeral by default; --evidence-db opts in to storing the run — its scan context and one immutable snapshot per finding — in a local SQLite database, so it can be verified and re-reported later without rescanning the target:

harvestguard scan ./project --type crypto --evidence-db ./evidence.db
harvestguard evidence list --evidence-db ./evidence.db
harvestguard evidence verify <scan-id> --evidence-db ./evidence.db
harvestguard evidence export <scan-id> --evidence-db ./evidence.db --markdown report.md

Stored runs are append-only and carry a SHA-256 digest that detects corruption or internal inconsistency; it is deliberately not a signature, not tamper-proof, and not a chain of custody, since anyone who can write the file can change both the data and the digest.

The database is a sensitive evidence artifact — it retains paths, object names, certificate subjects and issuers, and technical ownership signals — and it is not encrypted at rest. Protect it as carefully as the reports it can regenerate. See docs/CLI.md.

Running the dashboard

The Streamlit dashboard is a separate operating path: it runs from the repository root and is not part of the installed CLI package, so it uses requirements.txt rather than the packaging metadata.

pip install -r requirements.txt     # or pip3 if needed
streamlit run main.py

Running in a container

For deal data you'd rather not run through a bare Python environment: a non-root, distroless, read-only-filesystem-compatible image is provided.

docker build -t harvestguard .
docker run --rm -p 8501:8501 --read-only --tmpfs /tmp harvestguard

Local filesystem and PII/secrets scans need no network access at all — verified in SECURITY.md. Cloud scans need outbound access only to that provider's API; see deploy/iam/ for least-privilege, read-only IAM policy templates scoped to exactly what each scanner calls.

Version and Releases

HarvestGuard is pre-1.0. harvestguard --version prints the installed version, and every Markdown report records it in its Scan Information table, so an evidence artifact identifies the release that produced it. Release notes are in CHANGELOG.md; version identity, reproducibility expectations, SBOM/signing/provenance status, and the release procedure are in docs/RELEASE.md.

How to get it. python -m pip install harvestguard installs the released wheel from PyPI (pypi.org/project/harvestguard), and installing from a source checkout stays supported — it is what the demo corpus, the dashboard, and the test suite need, since none of them is part of the distribution. The container image is published from main and tagged by commit SHA, not by product version. Which distribution channels are supported, deferred, or deliberately out of scope is recorded in docs/RELEASE.md.

Pilot feedback wanted. v0.2.0 is a pre-1.0 pilot release, and it has been exercised mainly in the maintainer's own environment. If you install or run it, reports of what happened — including the boring successes — are useful. What to include, and what never to send, is in SUPPORT.md.

Support

SUPPORT.md covers where to ask a question, what version is supported, what to include in a bug report, and what support to expect — best effort through GitHub Issues, with no service-level agreement. Advisory work available separately from the maintainer is described there too, and is not a support tier for this repository.

Contributing

Contributions welcome — see CONTRIBUTING.md for dev setup, test/lint commands, good first-contribution areas, and the contribution workflow. Non-trivial changes should start from a GitHub Issue; roadmap IDs are planning references, not substitutes for issue scope. Product direction lives in docs/ROADMAP.md, docs/PRODUCT_PRINCIPLES.md, and docs/ARCHITECTURE.md.

Security

Found a vulnerability? Please don't open a public issue — see SECURITY.md for how to report it privately.