Portmaster Endpoint Network Audit

The following is AI-generated (aka vibe-coded) software. The software is specific to my needs and my system and may not work for you or your system. Support is limited, but if you report a bug I'll certainly look into it. All code is provided in a zip file for you to review should you choose.

Audits every program that Portmaster has seen make network connections. For each Portmaster profile whose executable is an EXE, it combines Portmaster’s connection history with what Windows says about the file and the running process: the Authenticode signature, SHA256, version information, who can write to the file and its folder, data streams, the running instances and their parents, modules loaded from unexpected places, scheduled tasks and Run keys that start it, the service it belongs to (svchost.exe services in depth), and its network behavior (periodic beacons, direct-to-IP traffic, rare destinations, uncommon ports).

Each item is rated PASS, REVIEW (something to look at) or FAIL (a hard contradiction, such as a missing file or a broken signature), with a concern level of low, moderate or high. The results go to a text, JSON, CSV and HTML report; a summary of the items that need attention is printed. The Portmaster database is opened read-only and is never changed.

Items you have reviewed can be added to a validated list, so later audits accept them while their identity and findings stay the same, and flag them again when either changes.

• Requirements
• Quick start
• Commands
• Command line
• Files in the working folder
• Keyboard shortcuts
• Testing
• Troubleshooting
• Limitations
• Changes to the command line

Requirements

• Python 3.8 or later. Nothing else to install.
• The audit needs Windows 10 or later, with Windows PowerShell, and is best run from an elevated prompt (see Troubleshooting). The other commands and --help run on any system.
• Portmaster’s history database (history.db, in Portmaster’s data folder when its network history is turned on).

Quick start

python portmaster-endpoint-network-audit.py --command audit --portmaster-db-file-path "PATH\TO\history.db"

The audit prints a summary of the FAIL and high-concern REVIEW items, and writes its reports to the working folder (%APPDATA%\portmaster-endpoint-network-audit unless you give --working-folder-path). Open the HTML report to sort and filter every item.

After reviewing the items in the summary, accept them:

python portmaster-endpoint-network-audit.py --command validate

The next audit reports them as validated, unless the file changes or a new finding appears.

Commands

Every run names its command with --command:

The summary shows, by default, the FAIL and high-concern REVIEW items that are not on the validated list. The --console-... options choose other items; the reports always have every item.

The validated list matches an executable by its path and SHA256. A shared host such as svchost.exe or rundll32.exe runs many unrelated components, so it is matched by its profile and the SHA256 of its ServiceDll too. A missing executable is added as a MISSING_FILE exception, which stops applying if a file appears at that path. The findings an item had when it was validated are remembered: a new one (a new scheduled task, beaconing, direct-to-IP traffic) puts it back in the summary as VALIDATION-CHANGED. Validating it again accepts the new findings.

The baseline (--write-baseline TRUE) records each executable’s SHA256, signer and destinations, so later audits report files that changed and destinations never seen before.

Command line

python portmaster-endpoint-network-audit.py --command audit|show|validate|prune|selftest [options]

Every option is written --name VALUE or --name=VALUE, in any order. A yes/no option takes TRUE or FALSE (also 1/0, YES/NO, ON/OFF, in any case). An option left out, or given blank, takes the default named below. --help lists them all.

Giving an option to a command it doesn’t apply to is a mistake (--detail-limit only applies to --command audit).

The beacon allowlist is a text file with one rule per line; # starts a comment. A rule is a glob matched against the host, IP, host:port and ip:port, in any case, optionally after profile=GLOB:

*.windowsupdate.com
profile=Firefox  push.services.mozilla.com:443
profile=Teams*   52.112.*

DNS, DNS over TLS, NTP, mDNS and LLMNR traffic, and traffic to the DNS servers this computer uses, are never beacons.

Results and messages: the summary (and what validate adds and prune removes) goes to stdout; the steps of the run, where the reports went, warnings (Warning: ...) and errors (Error: ...) go to stderr. During the audit, a progress line counts the profiles on the console; it is left out when stderr is redirected.

Exit codes say only whether the run worked, never what the audit found:

Files in the working folder

The JSON, CSV and HTML files, the validated list and the baseline are written through a temporary file, so an interrupted run never leaves a half-written one. A validated list or baseline that can’t be read as JSON is renamed <name>.damaged-<date and time>.json with a warning, and the run starts without it. A list or baseline that is valid JSON but not one this app writes stops the run (exit 1) and is left as it is.

Keyboard shortcuts

Ctrl+C stops a run (exit 1). The reports are not written; the text report has what the run reached.

Testing

python portmaster-endpoint-network-audit.py --command selftest
python -m pytest

The self-test checks the analysis without touching your files or Windows: timestamps, paths, signer matching, validated identities, the console filters, beacon detection and the allowlist, the validated list (a damaged one is kept aside, one of the wrong shape refused), the CSV’s encoding, the HTML report’s escaping, and pruning. Its last line before the result says whether the Windows audit can run here.

The tests (pytest) run the script as a separate process, with its own working folder, and build their inputs (an audit’s JSON report, a Portmaster database) in the test. They cover the summary and its filters, an empty result exiting with 0, exit codes 1 and 2 (every kind of command-line mistake), validating, a damaged or unusable validated list, pruning with and without a dry run, a history too short to prune, the default working folder, --help, --command selftest and a reader that stops early. 16 tests pass in about 5 seconds on Linux. The audit itself needs Windows, so the tests check only that it says so elsewhere; check an audit on Windows after changing it.

Troubleshooting

• Many “Loaded-module enumeration … was unavailable” or ACL notes: run the audit from an elevated prompt. Without administrator rights, Windows hides other users’ and system processes’ modules, and some files’ ACLs.
• “there is no audit report” with show or validate: run --command audit first, with the same --working-folder-path.
• “the history only covers about N day(s)” with prune: Portmaster’s history doesn’t reach back --inactive-days days, so an executable’s absence can’t be shown. Use a smaller number, or wait.
• “could not be read … kept as …damaged-…”: the validated list or baseline was damaged (for example by a crash while it was written by an older version). The run went on without it; the damaged file is beside it, to recover entries from by hand.
• “is not a validated list written by this app”: --validated-list-file-path points at another JSON file. The file was left as it is.
• A launcher passes None for an empty option: leave the option blank instead. None is not a number of days.

Limitations

• The audit needs Windows and Windows PowerShell; it reads Portmaster’s history but doesn’t talk to Portmaster.
• A beacon must have at least 5 connections whose intervals vary by no more than 20% (median absolute deviation), over at least --beacon-min-span-minutes. Beacons with more jitter, or sampled beyond --behavior-rows-per-profile, are not found.
• Direct-to-IP detection needs a history that records DNS names (a remote_host or domain column).
• show and validate use the identities in the last report; they don’t hash the files again. Run an audit first if files may have changed.
• A REVIEW or FAIL is a lead for a person to follow, not proof of malware.

Changes to the command line

This version follows the owner’s command-line templates. Earlier command lines need these changes:

The app was renamed from Windows Portmaster Endpoint Network Audit, so its default working folder and its files lost the windows- prefix. To keep an existing validated list, baseline and allowlist, move them from %APPDATA%\windows-portmaster-endpoint-network-audit to %APPDATA%\portmaster-endpoint-network-audit and drop the windows- prefix from their names (their formats haven’t changed). Otherwise the next audit starts without them.