Passive process forensics that hands your AI a real evidence file.
ProcWitness is a cross-platform process monitor for Windows, Linux, and macOS that records behavior locally and builds AI-ready forensic evidence. It listens for a selected period, performs expensive correlation on-device, removes low-value noise, stores the evidence on disk, and creates a ready-to-paste prompt for Codex or another AI. The AI interprets a prepared evidence package—it is not asked to collect or invent telemetry.
The release packages are self-contained; you do not need to install .NET or build the source code.
Open PowerShell, paste this line, and press Enter:
irm https://raw.githubusercontent.com/Teknesyum/ProcWitness/main/scripts/install.ps1 | iexThe installer downloads the latest release, installs it under %LOCALAPPDATA%\Programs\ProcWitness, creates a ProcWitness desktop shortcut with the application icon, and launches the app. Run PowerShell as Administrator when you want Windows ETW upload/download byte telemetry; the rest of the scanner also works without elevation.
Open a terminal, paste this line, and press Enter:
curl -fsSL https://raw.githubusercontent.com/Teknesyum/ProcWitness/main/scripts/install-linux.sh | bashThe installer places the application in ~/.local/share/ProcWitness, creates the procwitness command and adds ProcWitness to the desktop application menu. On a graphical session it launches the app automatically. No sudo is required.
If your minimal Linux installation does not already contain desktop libraries, install them once:
# Ubuntu / Debian
sudo apt update && sudo apt install -y libx11-6 libice6 libsm6 libfontconfig1You can then launch it from the application menu or run:
procwitnessOpen Terminal, paste this line, and press Enter. The installer automatically selects Intel (x64) or Apple Silicon (arm64):
curl -fsSL https://raw.githubusercontent.com/Teknesyum/ProcWitness/main/scripts/install-macos.sh | bashThe app is installed as ~/Applications/ProcWitness.app and opened automatically. The current package is not Apple-notarized. If macOS blocks the first launch, open Finder → Home → Applications, Control-click ProcWitness, choose Open, then confirm Open. This approval is normally needed only once.
Run the same one-line installer again. It downloads the newest GitHub release and replaces the existing installation while keeping locally collected analysis data.
Open ProcWitness from the desktop shortcut or application menu. Linux users can also run procwitness from a terminal. The app begins monitoring the process list and shows its collector status at the top.
On Windows, launching it as Administrator enables ETW per-process upload/download byte collection. If you launch it normally, process, CPU, memory, file, signature and connection analysis still works; the unavailable network-byte capability is clearly marked instead of being reported as zero traffic.
Open the Scan tab and click Scan now. The table is refreshed with the currently running processes and ordered by the local risk score.
- Select a row to see its executable path, SHA-256 hash and verified publisher.
- Click Open file location to reveal the selected executable in Explorer, Finder or your Linux file manager.
- Review the risk level and primary reason. A high score means “investigate first”, not automatic proof of malware.
- After the scan completes, Create prompt for analysis becomes available.
Use an instant scan when you want a quick snapshot. It cannot prove behavior that only becomes visible over time.
Open Timed Analysis and choose 1, 5, 10, 20 minutes, or enter a custom duration and click Start. Recording begins at the exact moment you press the button; older telemetry is not mixed into the session.
During recording:
- the Scan now control displays
Scanning • MM:SS; - the process table continues updating approximately every four seconds;
- CPU, RAM, file identity, active endpoints and available network counters are saved locally;
- wait until the countdown finishes—closing the app cancels the current session.
Suggested durations:
| Duration | Good for |
|---|---|
| 1 minute | quick CPU spikes and immediately active processes |
| 5 minutes | first-pass checks for miners and aggressive background traffic |
| 10–20 minutes | intermittent spyware behavior, periodic uploads and load changes |
| Custom | reproducing a known event, application launch or suspicious scheduled activity |
When recording finishes, ProcWitness correlates observations by executable path and SHA-256, filters stable low-value noise, calculates local findings, and writes a readable report. The prompt button appears only after this local work is complete.
Click Create prompt for analysis. The button changes to ✓ Copied to clipboard for confirmation. ProcWitness also saves the prompt next to the analysis bundle so the result is not lost if clipboard access fails.
Paste the prompt into Codex or another AI assistant. The prompt tells the AI where the local JSON evidence file is located, how its fields are organized, which platform capabilities were unavailable, and asks for an evidence-based report. If that AI cannot access files on your computer, attach the referenced analysis-*.json file manually.
A useful final report should include:
- a prioritized list of suspicious processes and the evidence for each one;
- likely benign explanations and confidence level;
- path, PID and SHA-256 for files that need further inspection;
- safe verification steps before deleting, blocking or terminating anything;
- an explicit note when evidence is insufficient.
Click Open data folder in Timed Analysis. The folder contains:
telemetry.jsonl— chronological local process snapshots;analysis-*.json— filtered and correlated evidence for a completed timed session;analysis-*.prompt.txt— the ready-to-paste AI instruction;instant-analysis-*.prompt.txt— prompts created from instant scans.
ProcWitness does not upload these files automatically. You decide if and where they are shared.
The Settings tab can enable an opt-in Anthropic, OpenAI, or compatible REST provider. It stores the API key with Windows DPAPI, macOS Keychain, or Linux libsecret when available; if secure Linux storage is unavailable, the key remains in memory for the current session only. Direct AI is disabled by default and every request shows the destination, payload size, process count, model, and estimated tokens for confirmation.
Only the bundle metadata, process summaries, persistence summary, and baseline comparison are sent by default. Raw snapshots require a separate setting. Paths and command-line secrets are redacted again immediately before transmission, and reports are saved locally as ai-report-*.md.
The same explicit workflow is available from the CLI:
procwitness report --bundle analysis-20260101-120000.json --ai
Use --yes only in automation where the provider and payload have already been reviewed.
Scores combine several indicators, including sustained CPU load, rapid changes, writable-path execution, recent binaries, unsigned network activity where signature verification exists, PID respawning and unusual network behavior. Normal developer tools, game launchers, backup clients and update services can trigger similar signals.
Do not delete a file solely because it appears near the top. Verify its path and publisher, compare its SHA-256 with a trusted source, scan it with your security product, and only then decide on remediation. If a process disappears when a system monitor opens, reproduce the behavior with a timed recording rather than relying on a single observation.
- CPU and memory behavior over time—not just a single snapshot
- executable path, creation time, SHA-256 identity, and platform signature status
- established remote endpoints attributed to individual processes
- sustained load, sharp CPU changes, recent binaries, writable-path execution, PID respawning, and signature/network combinations
- Windows Task Manager evasion patterns, where high load drops immediately after Task Manager starts
- abnormal upload/download behavior when the platform exposes per-process byte telemetry
- read-only persistence inventory across startup entries, scheduled tasks, services, systemd, cron, launchd, and login items
- running processes linked to persistence entries by executable path or SHA-256
- saved baselines and explicit added, removed, hash-changed, and new-persistence differences
Pressing Scan now creates an instant evidence set and enables the prompt button. Pressing 1, 5, 10, 20, or custom minutes starts a new capture at that exact moment. ProcWitness samples throughout the full interval, shows the countdown in the scan control, writes JSONL locally, creates a correlated JSON bundle, and only then enables the AI prompt.
A hidden window is not proof of malware, but sustained CPU use without a visible interface deserves context. ProcWitness records CPU over time, correlates samples by executable identity, and highlights sustained or sharply changing background load while preserving signature and network context. See What it detects and the rule details in DETECTION.md.
How to find a hidden crypto miner
Miners often combine sustained processor use, background execution, writable-path binaries, unsigned networking, or a sudden load drop when Task Manager opens. A timed capture preserves those changes instead of relying on the one instant visible in a task manager. Follow How to use ProcWitness and confirm every candidate by path, publisher, and SHA-256 before remediation.
On elevated Windows sessions, ProcWitness uses ETW to attribute upload and download byte deltas to processes; on every supported platform it also records available remote TCP endpoints. The evidence bundle relates traffic to executable identity and time, so an AI can judge whether the volume fits the program's role. Capability gaps are marked unavailable rather than misreported as zero; see Platform capabilities.
Task Manager is a live snapshot, Process Explorer is an excellent interactive process inspector, and antivirus products apply their own detection engines. ProcWitness complements them by passively recording a time window, correlating changing behavior locally, and packaging evidence for an AI-assisted investigation. It does not scan file contents, quarantine files, kill processes, or replace antivirus/EDR; read Privacy and responsible use.
| Capability | Windows | Linux | macOS |
|---|---|---|---|
| Process, CPU, RAM, path, hash | Yes | Yes, subject to /proc permissions |
Yes, subject to OS permissions |
| Code signature verification | Authenticode chain | Reported unavailable; never treated as unsigned | codesign --verify |
| Established TCP endpoints | IP Helper API | /proc/net/tcp* + socket inode/PID mapping |
lsof |
| Per-process upload/download bytes | ETW when elevated | Unavailable without a privileged eBPF collector | Unavailable without an entitled Network Extension |
| Task Manager evasion signal | Yes | Not applicable | Not applicable |
Missing telemetry is recorded as unavailable, never as zero activity or evidence of safety.
Data is stored under the operating system's local application-data directory in ProcWitness/data. The generated prompt contains the exact analysis bundle path, explains its schema, marks unavailable capabilities, and asks the AI to produce an evidence-based report. The app never uploads data unless you enable direct AI reporting and approve that specific request. It never kills processes, deletes monitored files, or quarantines software; the only deletion command removes ProcWitness's own local evidence after confirmation.
ProcWitness is a triage and investigation aid, not a replacement for antivirus/EDR or professional incident response.
Requires the .NET 9 SDK:
dotnet test ProcWitness.sln -c Release
dotnet run --project src/ProcWitness.App/ProcWitness.App.csprojCreate self-contained Windows x64, Linux x64, macOS x64, and macOS ARM64 archives:
./scripts/build-release.ps1 -Version 0.9.0The desktop UI uses Avalonia. Windows network-byte collection uses ETW; Linux and macOS adapters use native, read-only operating-system sources.
Release installers add procwitness to the user PATH. The CLI and desktop application use the same CaptureSession, risk rules, persistence inventory, baseline comparison, and bundle schema.
procwitness scan
procwitness scan --json
procwitness capture --minutes 5 --out bundle.json --format json
procwitness persistence --json
procwitness baseline save
procwitness baseline compare --file baseline-20260814-120000.json --json
procwitness prompt --bundle bundle.json
procwitness --version
Normal success returns exit code 0, runtime failures return 1, and invalid arguments return 2. Findings do not change the exit code unless scan --exit-code-on-high is explicitly requested. In JSON mode stdout contains only JSON; status and progress go to stderr.
procwitness mcp exposes the same local collection engine through a stdio MCP server. An AI client can list processes, start a non-blocking capture, poll progress, read a context-safe bundle summary, inspect persistence, compare a baseline, and request one process in detail. See the MCP setup and security guide.
- no automatic upload or cloud dependency
- user-profile paths are anonymized in compact AI summaries
- executable metadata is treated as untrusted input
- no destructive remediation actions
- only scan systems you own or are authorized to inspect
If ProcWitness saves you time, you can support continued development:
Created and maintained by Teknesyum. Source code is licensed under the MIT License.
Formerly released as "AI Scanner".