Known Process Database Format

Known-Process Database Format

Status: planned (v0.3.0). The KnownProcess type already exists in core; the embedded JSON database and its loader land in v0.3.0. This page documents the format so contributions can be prepared early.

hightower ships a curated list of well-known Windows processes, embedded into the binary at build time (include_str! + serde_json -- no network, no external file to lose). Each entry is a JSON object:

{
  "processName": "svchost.exe",
  "expectedDirectories": ["%SystemRoot%\\System32", "%SystemRoot%\\SysWOW64"],
  "publisher": "Microsoft Windows",
  "category": "core-windows",
  "descriptionEN": "Generic host process for Windows services; multiple instances running simultaneously is normal.",
  "descriptionPT": "Processo host genérico para serviços do Windows; ter várias instâncias rodando ao mesmo tempo é normal."
}

Fields

Field	Type	Meaning
processName	string	The executable's base name, e.g. "svchost.exe". Matched case-insensitively.
expectedDirectories	string[]	Directories the process legitimately runs from. May use placeholders like %SystemRoot%\\System32. Used by the path-masquerading rule.
publisher	string	The expected signer, e.g. "Microsoft Windows".
category	string	One of core-windows, driver, third-party-known, unknown.
descriptionEN	string	Plain-language description in English.
descriptionPT	string	Plain-language description in Portuguese.

Proposing a new entry

Adding a known process is a great first contribution. To keep the database trustworthy:

1. Only add widely and publicly documented processes. Cite your source in the PR description (Microsoft docs, a reputable reference).
2. Keep descriptions plain-language. A non-technical reader must understand them -- no jargon. Both descriptionEN and descriptionPT are required.
3. Get the expected directories right. They are what the masquerading rule trusts; an over-broad entry weakens the check for everyone.
4. Pick the narrowest correct category.

Open a pull request with the new object added to the database file. CI (fmt, clippy, test, audit) must pass.