Skip to main content

Brand impersonation detector

A self-hosted pipeline that finds accounts, ads, apps and domains impersonating a brand, ranks them for an analyst, and records every decision on them as signed evidence that anyone with the public key can verify offline. It runs on infrastructure you control.

It detects and documents. It does not file takedowns, contact platforms or act on any account; it produces report payloads that an operator reviews and files.

All brands, domains, handles and logos in the repository are fictional (reserved .test domains, synthetic logos drawn from basic shapes).

Why

Finding look-alike domains and accounts is the easy part. The questions come afterwards: who decided that a candidate was impersonation, what they were shown, which model and thresholds ranked it, and whether the record has changed since. A platform, a registrar or an internal reviewer asking them should not have to take the operator's database on trust.

The project is built around those questions:

  • A model ranks; a person decides. The triage policy rejects only clear negatives and sends everything else to a person. Automatic confirms are off unless you turn them on, and even then they stay open until a person looks.
  • Every decision is a signed receipt, rejects and reversals included. A receipt pins the bytes that were seen, the model and prompt template, the thresholds, the person and the authority they acted under. Receipts form a chain; bid verify checks one receipt or the whole chain with the public key alone.
  • People stay in charge of the queue. Declared people can stop it at any time, reversals need a declared releaser, and overdue holds are escalated. Each of these is a signed record too.
  • It runs where your data is. A deployment profile limits which hosts each component may reach, removes personal data before model calls, and the settings actually in effect are attested into the record.
  • It is open source under Apache-2.0, so the detection rules, the evidence format and the verifier can be read, audited and changed by the people who rely on them.

How it works

sensors -> normalize -> cheap filters -> classify -> rank
        -> triage policy -> person decision -> signed receipt -> offline verify
Stage What it does
Sensors Public sources: certificate-transparency logs, look-alike domains (dnstwist permutations resolved over DNS-over-HTTPS), username enumeration, Bluesky, the Apple App Store, the Meta Ad Library, and a fixture search.
Normalize Stores every observation and asset under its SHA-256, computes perceptual hashes, merges duplicates.
Cheap filters Deterministic signals with no model call: confusable-folded handle distance, Jaro-Winkler similarity, logo pHash (optional CLIP), brand alias in text, official-domain mismatch, known-bad domains.
Classify Rule-based offline classifier by default; a hosted multimodal model with --live. Scraped text is treated as untrusted data, and injection attempts count as a signal. Optional recheck by a model of another family.
Triage and decisions Every verdict gets a signed receipt. A person confirms, rejects or escalates in the console; a declared releaser can reverse a confirm.
Output Report payloads from a confirmed finding (platform report, registrar abuse report, fraud-desk case, findings log, STIX 2.1), checked against policy packs.

Details: architecture · evidence format · governance.

Quickstart

Python 3.11 or later.

git clone https://github.com/chernistry/brand-impersonation-detector
cd brand-impersonation-detector
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[console]"

bid run          # whole pipeline on the bundled fixtures: no keys, no accounts, no network
bid verify .bid/pipeline/receipts.jsonl --pubkey "$(cat .bid/pipeline/ed25519_pubkey.txt)"
bid console      # operator console on http://127.0.0.1:8799

bid run exits 0 only when the HMAC chain and the public-key check pass, both tamper checks (an asset byte and a manifest field) are caught, and every candidate has a receipt. Fixture runs are deterministic: two runs produce byte-identical signed evidence (bid replay checks this).

Fixture runs use public development keys, so their receipts prove nothing. Set your own keys before real use (deployment).

Tamper check

Change one byte of a stored asset and verify again:

cp -R .bid/pipeline /tmp/bid-copy
python - <<'EOF'
import json, pathlib
d = pathlib.Path("/tmp/bid-copy")
h = json.loads((d / "receipt_sample.json").read_text())["manifest"]["asset_hashes"][0]
b = bytearray((d / h).read_bytes()); b[-1] ^= 1; (d / h).write_bytes(bytes(b))
EOF
bid verify /tmp/bid-copy/receipts.jsonl --pubkey "$(cat /tmp/bid-copy/ed25519_pubkey.txt)"
# RESULT: REJECTED  (package 0 failed: asset ... bytes tampered (hash no longer matches))   exit 2

Container

for v in BID_CONSOLE_TOKEN BID_HMAC_KEY BID_ED25519_SEED BID_LEDGER_KEY; do
  export "$v=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
done
docker compose up --build              # console on http://127.0.0.1:8000
docker compose run --rm console run    # one pipeline run in the same image

The image runs as a non-root user with a read-only root filesystem and all state in /data.

Commands

bid <command> --help shows the options of each command.

Command Purpose
bid run run the pipeline and verify the evidence it signs (--brands, --sensors broad, --live, --recheck, --profile, --policy-pack, --anchor, --embeddings)
bid verify verify a receipt or a chain with the public key only
bid console operator console (needs the console extra)
bid governance stop or resume the queue, release a confirm, escalate overdue holds, show status, verify the journal
bid project project a confirmed finding into a report payload
bid packs check a notice against a policy pack; best-effort report over receipts
bid conduct signed conduct review of the classifier on the labelled set
bid replay prove two runs are byte-identical; show which policy produced a receipt
bid eval, bid agreement, bid scale, bid adversarial, bid compare-models evaluation (docs)
bid brand-kb draft brand aliases and official domains from Wikidata
bid demo-sensors, bid demo-enrich, bid demo-itunes run one live sensor or the public-source pivot

Configuration

Environment variables; the full list is in deployment.

Variable Effect
BID_DATA_DIR where all runtime state goes (default ./.bid)
BID_HMAC_KEY, BID_ED25519_SEED, BID_LEDGER_KEY signing keys; default to public development values
BID_CONSOLE_TOKEN required for the console to listen beyond loopback
BID_CONSOLE_ACTOR_HEADER take the acting person from an authenticating proxy's header
BID_LLM_BASE_URL, BID_LLM_API_KEY model endpoint and its key, for example a self-hosted model
OPENROUTER_API_KEY hosted model via OpenRouter; sent to openrouter.ai only
META_AD_LIBRARY_TOKEN, SHODAN_API_KEY optional live sources
BID_CONTACT contact appended to the User-Agent of outbound requests

With --live or --sensors broad, a .env file in the working directory is read for API keys; it never overrides a variable that is already set.

Documentation

Page Covers
Architecture stages, modules, runtime data layout, interfaces
Evidence format receipt fields, hashing, chain, verification
Governance triage, holds, decisions, release, queue stop, settings
Deployment keys, container, console access, profiles, egress, model endpoint
Projections report payloads from a confirmed finding
Policy packs notice checks and evidence reports per rule or jurisdiction
Evaluation what the measurements show and what they do not
Threat model assets, boundaries, threats, controls, residual risk

Limits

  • Detection and evidence only. A person reviews every finding; the tool does not perform takedowns or contact platforms.
  • Coverage is only as broad as the enabled sensors. There is no native ingestion from the large social networks, the Meta Ad Library API returns commercial ads only for the EU and UK, and Bluesky is a small slice of social media. Sensors are subject to each service's terms and rate limits; set BID_CONTACT.
  • A registered look-alike handle or domain is a lead, not proof of abuse.
  • The offline classifier is a rule table, not a trained model. The bundled labelled set is small and synthetic: it checks consistency and regressions, not accuracy on real traffic.
  • Prompt-injection defences reduce risk; they do not cover adaptive attacks.
  • Receipts are tamper-evident and verifiable offline. They are not a statement about legal sufficiency or admissibility in any jurisdiction, and the policy packs are unreviewed mappings, not legal advice.
  • The console token admits people but does not tell them apart; per-person identity needs an authenticating proxy.

Development

pip install -e ".[dev,console]"
python -m pytest -q
ruff check bid tests

See CONTRIBUTING.md for the ground rules and SECURITY.md to report a vulnerability.

Author

Built by Alex Chernysh. Help with deploying or adapting it: alexchernysh.com/consulting. Also by the author: Bernstein, an open-source governance layer for AI agents.

Licence

Apache License 2.0. See LICENSE and NOTICE.

Metadata

Release files for brand-impersonation-detector 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for brand-impersonation-detector 0.1.0
File Size Uploaded Provenance Actions
brand_impersonation_detector-0.1.0.tar.gz 318.4 kB With provenance Details for brand_impersonation_detector-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for brand-impersonation-detector 0.1.0
File Interpreter ABI Platform Actions
brand_impersonation_detector-0.1.0-py3-none-any.whl Python 3 none any Details for brand_impersonation_detector-0.1.0-py3-none-any.whl

Total release size: 631.0 kB

Release files / brand_impersonation_detector-0.1.0.tar.gz

Download URL brand_impersonation_detector-0.1.0.tar.gz
Size 318.4 kB
Tags Source
SHA-256 checksum
How to use checksums
53f1eb4b46c2c6d7ad700b9b2e385ee030a6a5deeaca7419646cd67e6c9f122a
BLAKE2b-256 checksum
How to use checksums
ece96bc308eb7141b119fab285d29f0adef16a4b55800689c6b9018ba68830e7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / brand_impersonation_detector-0.1.0-py3-none-any.whl

Download URL brand_impersonation_detector-0.1.0-py3-none-any.whl
Size 312.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4b427a3f76ca804b9a1364b27f6e055cce817719ec137794bb48b8984ebdaf8e
BLAKE2b-256 checksum
How to use checksums
f87bed4512e99625804255688abc4f6359e4993634c82f9dbc53929f9ccbb3c7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Security for brand-impersonation-detector 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for brand_impersonation_detector-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page