Skip to content

Similarity Engine

The similarity engine keeps a local memory of every file PPEE has analyzed. When you open a new file, it tells you whether you have seen the same file, or something close to it, before.

sequenceDiagram
    participant U as You (GUI / CLI / MCP)
    participant P as PPEE
    participant DB as <exe>.similarity.db
    U->>P: open / --similarity / check_similarity
    P->>P: MD5, SHA-256, Authentihash, ImpHash, SSDEEP, TLSH
    P->>DB: compare against all records
    DB-->>P: matching peers
    P->>DB: record this file
    P-->>U: toast / "Match against N peer(s)" / JSON matches

Matching rules

Check Match when
MD5 / SHA-256 Equal → reported as MD5 identical / SHA256 identical (exact duplicates are reported only once)
Authentihash Equal → Auth
ImpHash Equal → Imp
SSDEEP Score ≥ threshold (default 60) → ssdeep s=NN
TLSH Distance ≤ threshold (default 50) → TLSH d=NN

Files connected by any chain of matches form a cluster, and the GUI colors clusters consistently in the history window.

Where the data lives

  • Database: <executable name>.similarity.db (SQLite) next to the executable, for example ppee.similarity.db and ppee-cli.similarity.db. The GUI and CLI each keep their own database.
  • It stores each file's path and hashes, never file content.
  • Delete it from Settings → Clustering, or delete the file.

Privacy and read-only environments

The database records full paths of everything you open. On shared machines, in CI, or on read-only file systems, use --no-similarity, or turn the engine off in the GUI.

If the database can't be created or opened (a read-only folder or container), the CLI and MCP server say so instead of pretending there was no match: a warning: similarity database '…' could not be opened line on stderr, Similarity DB: unavailable in the text report, and "available": false in the JSON.

Using it from each interface

Enabled by default. Matches appear as toasts and in the history window.

Similarity toast

$ ppee-cli --similarity new.exe
Similarity DB: 2 record(s)
Match against 1 peer(s):
  SHA256 identical - /samples/old.exe

The CLI enables every check (including SHA-256) with the default thresholds. It waits up to 2 seconds for the lookup; on very large databases, a lookup still running at that point is reported as no match.

Bind-mount a database file to /ppee/ppee-cli.similarity.db to keep it between runs. See Docker → Persisting the similarity database.

check_similarity lets an assistant ask "have we seen this before?"

References