Logicytics

Reliable Windows evidence collection, organized around one verified run at a time.

Logicytics is a Windows evidence collection framework. It validates every collector before use, runs each one in isolation, and keeps the result in a manifest-backed run folder. A collector can succeed, skip, or fail without obscuring the rest of the verified run.

The complete user and developer manual is in docs/README.md and is mirrored to the Logicytics Wiki.

Use Logicytics only on systems and data you are authorized to inspect.

Start here

The installer is the only command intended to run outside the managed virtual environment. Run it once from the repository root:

python -m logicytics.cli.installer

Then activate the environment and check the installation:

.\.venv\Scripts\Activate.ps1
python -m logicytics preflight

When preflight reports no invalid collectors, make a plan and run it:

python -m logicytics plan --profile standard
python -m logicytics run --profile standard --acknowledge-authorization

If a normal command says the environment is missing, run the installer. If it says the environment is not active, run .\.venv\Scripts\Activate.ps1 first.

Choose a run

Every run validates collectors, records a manifest, and packages the result unless --no-package is supplied.

Need	Command
Fast local inventory	python -m logicytics run --mode quick --acknowledge-authorization
Everyday collection	python -m logicytics run --mode balanced --acknowledge-authorization
Deterministic sequential collection	python -m logicytics run --mode standard --acknowledge-authorization
Local-only collection	python -m logicytics run --mode offline --acknowledge-authorization
Extended collection	python -m logicytics run --mode thorough --acknowledge-authorization
Thorough duration report	python -m logicytics run --mode thorough --acknowledge-authorization --performance-check

thorough can include administrator-only collectors. Start an elevated shell when the plan reports that requirement. See every available mode with python -m logicytics --modes. Add --performance-check to any run --mode ... command to time that mode's selected collectors serially.

For offline collection from removable storage, add --usb to preflight, plan, run, or collector. It scans A: through Z: and uses the first drive containing Windows; use --usb=E to select a specific Windows drive. USB mode rejects output, cache, and temporary storage on that Windows disk.

Where results go

Each run receives its own directory under output/data/:

output/data/run/<fingerprint-prefix>/
  manifest.json          # status, collector results, and artifact catalog
  artifacts/             # collected evidence
  logs/                  # run and collector JSONL events
  reports/               # generated summaries

output/data/zip/<fingerprint-prefix>.zip
output/data/hashes/<fingerprint-prefix>.zip.sha256

The console is intentionally brief. Use manifest.json to inspect a run, the package hash to verify a package, and output/logs/Logicytics.log for the human-readable application log. Interaction history and its usage graph live in .cache/, which is created automatically. Worker scratch files default to project-local .temp/; set runtime.temporary_directory: system in logicytics.yaml to use %TEMP%/logicytics/ instead. The fingerprint is a SHA-256 identity derived from the immutable run ID; output uses its shortest unique prefix, starting at eight characters and extending only on a collision. Set logging.level: DEBUG in logicytics.yaml when you need detailed worker lifecycle information and file call sites.

Useful commands

# Revalidate every collector instead of reusing cached preflight probes
python -m logicytics preflight --invalidate-cache

# Inspect a plan without collecting evidence
python -m logicytics plan --profile standard

# Run one collector only
python -m logicytics collector core.system.system_info --acknowledge-authorization

# Run the complete test suite
python -m logicytics.cli.tests

# See diagnostics, configuration, and maintenance state
python -m logicytics debug

Use python -m logicytics --help or append --help to any command for its full flags.

Configuration and extensions

logicytics.yaml is the single user configuration file. It controls output locations, worker limits, logging, optional Sysinternals setup, and declared collector settings. Keep credentials and secrets out of it.

Core collectors are shipped and validated as part of the application. Plugins are opt-in and must pass the same validation boundary before they can run.

• Configuration reference
• Output contract
• Migration guide
• Flow matrix

Help and contributing

The Logicytics Wiki covers setup, troubleshooting, collector development, architecture, and security in more depth.

For changes to Logicytics, read CONTRIBUTING.md. Please also review SECURITY.md and CODE_OF_CONDUCT.md.

License

Logicytics is released under the project license.