Troubleshooting and FAQ

🩺 Troubleshooting and FAQ

Symptom → cause → what to do. Most entries are about proving the negative, not about crashes: an empty result is usually a coverage problem, not a quiet attacker.

← Home

---

Collection

Get-WinSecEventByIp returns nothing

Work through this in order:

Get-WinSecLogCoverage -LogName Security          # retention, size, accessibility
Test-WinSecAuditPolicy                           # is the subcategory even audited?
Get-WinSecEventByIp 203.0.113.7 -LastDays 30 -Profile All -DeepScan

1. Window too narrow. -LastHours 24 on a log that wraps every 6 hours proves nothing.
2. Audit policy off. Without "Audit Logon" you will never see 4624/4625.
3. IP embedded in a message. Use -DeepScan (drops the server-side IP gate).
4. Wrong profile. -Profile All widens the scope.
5. Wrong host. Confirm -ComputerName and that the event was logged on that host.

Warning

"No events" is a statement about the collected window. Say so in the report; do not upgrade it to "no activity".

Access is denied reading the Security log

Run the session elevated. The Security channel requires Administrator; there is no supported workaround. In a remote sweep this appears as Skipped with an access-denied note in LogDetails, while other channels continue.

A channel is missing (Sysmon, RDP, Firewall)

Expected on servers without those roles. Since 2.1.0 each channel is queried separately: the channel is Skipped, the rest of the sweep completes.

$rows = Get-WinSecEventByIp 203.0.113.7 -LastHours 12 -PassHostStatus
$rows[0].LogDetails | Format-Table LogName, Status, EventsFound, Error

Remote hosts fail

Status	Meaning	Check
Failed	transport or credentials	WinRM enabled, firewall, Test-WSMan, credential rights
Skipped	channel/log unavailable or access denied	elevation on the target, channel installed
NoEvents	query ran, nothing matched	window, profile, IP

Test-WSMan SRV01
Invoke-Command -ComputerName SRV01 -ScriptBlock { whoami; Get-WinEvent -ListLog Security }

For HTTPS transport pass -SessionOption (New-PSSessionOption -UseSSL). CredSSP is needed only for double-hop scenarios and should be enabled deliberately.

-ComputerName used to abort with "A ForEach-Object -Parallel using variable cannot be a script block"

Fixed in 2.1.0. If you see it, you are running 2.0.x — upgrade.

Collection crashed with "Cannot convert null to DateTime"

Fixed in 2.1.0: -LastHours, -LastDays and EVTX mode worked only when an explicit window was supplied. Upgrade, or pass -StartTime/-EndTime as a workaround on 2.0.x.

Analysis

No brute-force finding although there were many failures

Check the threshold and the window:

$findings = $events | Test-WinSecBruteForce -WindowMinutes 60 -FailureThreshold 3

Failures spread over hours do not exceed a 10-minute window. Also confirm the events are failures (Outcome -eq 'Failure') and carry the source IP.

Sessions look incomplete

Get-WinSecLogonSession needs 4624 and 4634/4647. If the profile excluded logoff events, sessions stay open. Use -Profile IncidentResponse or -Profile All, and remember that a missing 4634 can genuinely mean the session is still open.

Timeline has no buckets

Get-WinSecIpTimeline needs events with TimeUtc. An empty pipeline returns nothing; check that the previous command actually produced events.

Reporting

Where are the reports?

<OutputDirectory>/<CaseId>-reports/ — deliberately outside the evidence bundle. The bundle contains its own report.html/report.md, which are evidence artifacts, not narrative reports.

The abuse report has no recipient

NeedsContact = true means the ASN/PTR did not match a known abuse desk. Pass -ContactEmail 'abuse@example.net'. The tool never guesses an address.

Account names are visible in the attached CSV/JSON

Use -RedactAccounts. Since 2.1.0 redaction covers the body and the attachments with consistent pseudonyms.

The .eml does not open in my mail client

The file is UTF-8 with CRLF line endings and a multipart/mixed body. If your client refuses it, send the .md version through a web form or paste the body into a new message and attach events.csv manually.

Evidence

Test-WinSecEvidenceIntegrity reports Extra

A file exists in the bundle folder that the manifest does not list — usually a report written into the case folder, or a manually copied file. Reports belong in <CaseId>-reports/. Remove the extra file or document it; do not regenerate the manifest to hide it.

Modified on a file nobody touched

Check line-ending conversion (Git, editors) and any antivirus rewriting the file. Compare LastWriteUtc in the report. Re-export from the source if the content really changed.

Missing after copying

Copy the whole folder, not selected files. Case-sensitive file systems and cloud sync tools that rename files also cause this.

Configuration

config.json is ignored

Check the path printed by:

Get-WinSecHunterOption -ShowResolved

WINSECHUNTER_CONFIG_DIR overrides the default. A corrupt file is ignored with a warning; fix or delete it.

API key is "present" but the provider fails

-ShowResolved only checks presence. Verify the key works with a single lookup and check egress/firewall. OTX and AbuseIPDB require HTTPS; ip-api's free tier is HTTP-only and is intended for lab use.

Platform

Module does not import on Linux

It should: analysis and reporting are cross-platform. Collection cmdlets throw PlatformNotSupportedException by design. If import fails, check PowerShell version (7.6+) and that the whole module folder was copied.

auditpol output looks empty or garbled

auditpol /r output is parsed by column position, so localized Windows is supported. An empty result usually means the process is not elevated.

FAQ

Does it modify the event logs? No. Collection is read-only; Trace-WinSecIp bookmarks by record id.

Does it phone home? Only to the enrichment provider you explicitly enable, plus reverse DNS. No telemetry.

Can I run it from a USB stick? Yes — set WINSECHUNTER_CONFIG_DIR inside the stick; reading works from read-only media.

Does it support Windows PowerShell 5.1? No, and it will not: the module requires PowerShell 7.6+ (Core).

How do I cite a finding? Case id + artifact + SHA-256 from manifest.json + UTC timestamp. Test-WinSecEvidenceIntegrity gives you the verification line.

Reporting bugs

If the tool fails or contradicts the documentation, open an issue: https://github.com/paulmann/Get-Windows-Security-Events-By-IP/issues/new/choose

Include the module version, PowerShell version and OS, the exact command (redacted), expected vs actual behaviour, and Get-Error | Out-String. For collection problems attach the -PassHostStatus output with LogDetails and state whether the session was elevated.

Never paste API keys, personal data, raw event dumps or evidence bundles. Security issues go through SECURITY.md, not a public issue.