hMailServer + Kaspersky Cleanup#

Repository and developer#

Table of contents#

• Why this exists

• Repository contents

• How it works

• Requirements

• Quick start

• Operating modes

• Parameters of Invoke-HMailKasperskyCleanup.ps1

• Artefacts of a run

• The remediation plan

• Test-AvpCli.ps1: the behaviour harness

• Exit codes of avp.com

• Field-measured behaviour

• Safety guarantees

• Scheduling

• Troubleshooting

• Security notes

• License

Why this exists#

hMailServer can hand incoming mail to an external virus scanner, but that only protects what arrives after the integration works. A store that has been running for years usually contains messages that were accepted before the scanner was configured, or while its databases were stale, or while the integration silently failed.

A plain avp.com SCAN C:\mail\Data /i2 is not an acceptable answer for a mail store:

• the antivirus would modify or delete .eml files behind hMailServer's back, leaving the database pointing at files that no longer exist;

• .eml and mbox folder files are containers — the verdict belongs to an object inside the message, and only the whole message can be removed safely;

• the console client returns non-zero codes on perfectly successful runs, so a naive wrapper throws away exactly the batches that found something.

This toolkit therefore separates detection from deletion: Kaspersky always runs with /i0 (report only), the findings are correlated with real hMailServer messages over COM, written into a reviewable plan, and only a second, explicit run consumes that plan.

Repository contents#

How it works#

flowchart TD
    A([pwsh 7.2+, elevated, interactive session]) --> B{Mode}

    B -->|Preflight| P1[Resolve avp.com<br/>multi-stage discovery + HELP health probe]
    P1 --> P2[Capability matrix:<br/>Cmd vs Direct runner, ANSI/OEM list vs direct args, with/without /RA]
    P2 --> P3[(preflight-matrix.json)]
    P3 --> STOP([stop])

    B -->|Scan / Plan| S1[Resolve avp.com]
    S1 --> S2[Resolve hMailServer Data directory<br/>COM to INI to registry to install path]
    S2 --> S3[Enumerate *.eml, optional -SinceDays filter]
    S3 --> S4[(manifest-before.json<br/>SHA-256 per file)]
    S4 --> S5[Batched SCAN with /i0<br/>report only, nothing is touched]
    S5 --> S6[Parse report body and statistics block<br/>verdict families: EICAR, HEUR:, UDS:, VHO:, PDM:, Trojan, Exploit, Worm, ...]
    S6 --> S7[Coverage check:<br/>intended vs scanned vs vanished vs failed batches]
    S7 --> S8[Correlate detections with messages over COM<br/>domains to accounts to INBOX and IMAP folders]
    S8 --> S9[(remediation-plan.json<br/>infected-messages.csv)]
    S9 --> REVIEW([human review])

    B -->|Delete| D1[Load plan, verify schema 5<br/>and that DataDirectory still matches]
    D1 --> D2[Re-enumerate over COM<br/>match by MessageId + file path]
    D2 --> D3{Quarantine enabled?}
    D3 -->|yes| D4[Copy .eml to quarantine\<stamp><br/>failure aborts that message]
    D3 -->|no| D5
    D4 --> D5[DeleteByDBID via COM<br/>ShouldProcess / -WhatIf honoured]
    D5 --> D6[Optional -DeleteOrphan for unmatched .eml<br/>only inside the store, only *.eml]
    D6 --> D7([run.log, then re-run Scan to verify])

Three design decisions carry the whole tool:

1. Verdicts come from the report, not from the exit code. A scan that finds an object it cannot process returns exit code 3 while the task itself completes and writes a full report. 0, 3, 101 and 102 are treated as non-fatal; the decision is made from the report body and its ; Total detected: statistics block.

2. avp.com is discovered, then proven alive. A pending or failed upgrade leaves a second product folder behind, and that stale build accepts invocations and answers nothing. Every candidate is asked for HELP; only a build that answers is used. Newest-folder-wins is not sufficient.

3. Deletion goes through hMailServer, never through the antivirus. DeleteByDBID keeps the database and the file system consistent; the scanner never has permission to touch the store.

Requirements#

• Windows with PowerShell 7.2 or newer (pwsh), run elevated.

• An interactive session in which the resident Kaspersky process (avp.exe) is running. Without it the console client cannot execute tasks.

• A Kaspersky build whose avp.com answers HELP (consumer line or Endpoint Security).

• hMailServer with a working COM registration (hMailServer.Application) and the Administrator password.

• Reports and quarantine directories located outside the message store; the script refuses to run otherwise.

Quick start#

# 0. Prove that the console client is usable on this host and see which invocation forms work
.\Invoke-HMailKasperskyCleanup.ps1 -Mode Preflight

# 1. Optional: full behaviour matrix of avp.com on this build (EICAR based, disposable lab)
.\Test-AvpCli.ps1 -Runner Both

# 2. Audit the last 24 hours, report only, nothing is modified
.\Invoke-HMailKasperskyCleanup.ps1 -Mode Scan -SinceDays 1 -BatchSize 40

# 3. Audit the whole store, keeping every batch artefact for inspection
.\Invoke-HMailKasperskyCleanup.ps1 -Mode Scan -UpdateDatabases -KeepBatchArtifacts

# 4. Review, then remediate from the reviewed plan (dry run first)
$plan = 'C:\mail\reports\kaspersky\run-20260811-221500\remediation-plan.json'
.\Invoke-HMailKasperskyCleanup.ps1 -Mode Delete -PlanPath $plan -WhatIf
.\Invoke-HMailKasperskyCleanup.ps1 -Mode Delete -PlanPath $plan

Use Test-AvpCli.ps1 as a locator from your own scripts:

$avp = .\Test-AvpCli.ps1 -ResolvePathOnly -Quiet
& $avp.Path SCAN 'C:\mail\spool' /i0

# or cache the result for another process
.\Test-AvpCli.ps1 -ResolvePathOnly -PathFormat Json -Quiet | Set-Content .\avp-location.json

Operating modes#

Parameters of Invoke-HMailKasperskyCleanup.ps1#

A single instance is enforced through a global mutex (Global\Invoke-HMailKasperskyCleanup).

Artefacts of a run#

Everything lands in <ReportDirectory>\run-yyyyMMdd-HHmmss\:

Quarantine copies go to <QuarantineDirectory>\<stamp>\<account>_<id>_<file>.bad.

The remediation plan#

{
  "Schema": 5,
  "CreatedUtc": "2026-08-11T19:15:00.000Z",
  "Mode": "Scan",
  "DataDirectory": "C:\\mail\\Data",
  "AvpPath": "C:\\Program Files (x86)\\Kaspersky Lab\\Kaspersky 21.25\\avp.com",
  "Capability":  { "Runner": "Cmd", "Scope": "ListAnsi", "UseReport": true },
  "Statistics":  { "Processed": 18422, "TotalOk": 18420, "Detected": 1, "Suspicions": 1, "Skipped": 1, "Corrupted": 0, "Errors": 0 },
  "Coverage":    { "Intended": 18422, "Scanned": 18422, "Unscanned": 0, "VanishedAfter": 0, "FailedBatches": 0, "Complete": true },
  "Detections":  [ { "Path": "...\\{ID}.eml", "Verdict": "HEUR:Exploit.MSOffice.Generic", "InnerObject": "//attachment.rtf//equation", "Detected": true, "Skipped": true } ],
  "MatchedMessages": [ { "Account": "user@example.com", "Folder": "INBOX", "MessageId": 40213, "Subject": "Official Purchase Order", "Verdict": "HEUR:Exploit.MSOffice.Generic" } ],
  "Orphans": []
}

Delete mode refuses a plan whose Schema is not 5, or whose DataDirectory no longer matches the resolved store, or that references any path outside the store. Entries that changed since the scan are skipped and counted rather than deleted blindly.

Test-AvpCli.ps1: the behaviour harness#

The harness answers a single question: what does this particular Kaspersky build actually accept? It builds a disposable corpus from the EICAR test string — plain file, file in a Cyrillic directory, .eml with a base64 attachment, mbox folder file, ZIP archive — and then records, per case, the exit code, elapsed time, the first line of output, whether /RA and /R produced a report, how many verdicts appeared, and whether the target survived.

Key switches: -Runner Cmd|Direct|Both, -SkipEicar (clean corpus only, for a pure syntax matrix), -IncludeDestructive, -SkipAuthProbe, -SkipLivenessProbe, -ResolvePathOnly with -PathFormat Object|Path|Json, -Quiet.

Outputs land in <LabRoot>\output\: avp-cli-matrix.csv, avp-cli-matrix.json, summary.md and harness.log.

Credentials are handled carefully. Endpoint Security accepts /login=<user> together with /password=<secret>; the consumer line accepts /password only and has no account name. Credentials are appended solely to commands documented as protected (ACTIVATE, ADDKEY, DISABLE, EXIT, EXPORT, IMPORT, LICENSE, MDRLICENSE, PAUSE, RESTORE, RESUME, SELFPROTECTION, STOP). Invalid credentials are never probed, because repeated failures lock the Password-protection account.

Exit codes of avp.com#

Field-measured behaviour#

Everything below was measured on a live server, not assumed:

• Exit code 3 is normal on a productive store. An earlier revision discarded exactly those batches and reported zero detections on a store that did contain an exploit-carrying message.

• UTF-16 scope lists are rejected by this product line and waste minutes doing so, so only ANSI and OEM lists — plus direct arguments with a bounded command line — are considered.

• SCAN and UPDATE do not accept /login or /password. Passing them breaks the invocation, so credentials are never appended to those commands.

• A stale product folder behaves like a working one. It accepts the invocation and returns 3 with no output for every command, which fills a matrix with identical meaningless failures. Hence the HELP health probe.

• Verdicts describe container hierarchies, for example <path>.eml//attachment.rtf//equation → suspicion → HEUR:Exploit.MSOffice.... The base .eml path identifies the hMailServer message; the remainder identifies the object inside it. Lines that only say ok, or that describe an archive layer, carry no verdict and are ignored.

• Report parsing is bilingual. English and Russian state words (suspicion / detected / skipped and the Cyrillic equivalents) are all recognised, and report files are decoded from BOM, UTF-16 or the OEM code page.

Safety guarantees#

• Kaspersky is always invoked with /i0. The antivirus never modifies or deletes anything in the store.

• Deletion happens only in Delete mode, only from a plan you have reviewed, and only through the hMailServer COM API.

• SupportsShouldProcess with ConfirmImpact = 'High': -WhatIf and -Confirm work as expected.

• Reports and quarantine must live outside the message store; the script throws if they do not.

• Orphan removal refuses anything that is not a *.eml file inside the store.

• A failed quarantine copy aborts the deletion of that message.

• Every path from a plan is re-validated against the current store before use.

• A global mutex prevents two concurrent runs.

• The Administrator password lives only as a SecureString; the harness additionally masks secrets in the log, CSV, JSON and console, and in the Cmd runner passes the password through a process environment variable substituted by cmd.exe.

Scheduling#

Because the console client needs the resident process in an interactive session, a fully unattended full-store scan is not always possible. A practical compromise is a daily audit-only run that alerts a human:

$action  = New-ScheduledTaskAction -Execute 'pwsh.exe' `
  -Argument '-NoProfile -File "C:\tools\Invoke-HMailKasperskyCleanup.ps1" -Mode Plan -SinceDays 2'
$trigger = New-ScheduledTaskTrigger -Daily -At 03:30
Register-ScheduledTask -TaskName 'hMail Kaspersky audit' -Action $action -Trigger $trigger -RunLevel Highest

Then review infected-messages.csv and run Delete by hand.

Troubleshooting#

Security notes#

This toolkit removes mail from a production store. Treat it as a privileged operation: keep the report directory on a volume with an audit trail, keep quarantine copies until you are certain, and never point -DataDirectory at anything you have not backed up. Findings such as HEUR:Exploit.MSOffice.* on an //equation object mean the message reached a mailbox — investigate whether it was opened, not only whether it is gone.

License#

PolyForm Noncommercial 1.0.0 — see LICENSE.

Author#

Mikhail Deynekin — git@deynekin.com · https://deynekin.com/ · @paulmann

If this saved you an incident, a star is appreciated. Issues and pull requests with real report excerpts from other Kaspersky builds are especially welcome.