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 verifychecks 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
Metadata
Release files for brand-impersonation-detector 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| brand_impersonation_detector-0.1.1.tar.gz | 318.5 kB | With provenance | Details for brand_impersonation_detector-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| brand_impersonation_detector-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for brand_impersonation_detector-0.1.1-py3-none-any.whl |
Total release size: 631.1 kB
Release files / brand_impersonation_detector-0.1.1.tar.gz
| Download URL | brand_impersonation_detector-0.1.1.tar.gz |
|---|---|
| Size | 318.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
67ed9a22e4a341af92a62e3449af388349b1d96e8eebeddfb0b668d51aef179d
|
|
BLAKE2b-256 checksum How to use checksums |
b40e478f487a0fa3f82d09dfa3acf59405895537ed8858ffc3106bfa8fd7e0a9
|
| 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 logRelease files / brand_impersonation_detector-0.1.1-py3-none-any.whl
| Download URL | brand_impersonation_detector-0.1.1-py3-none-any.whl |
|---|---|
| Size | 312.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f41c66a2c4187308a86bcc621eee942e9530842ea87f844c020fa303af11668d
|
|
BLAKE2b-256 checksum How to use checksums |
3f8f203eccee238f5db8d65a4e6180af1568d8eb734d2ffc09220532aea22489
|
| 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 logSecurity for brand-impersonation-detector 0.1.1
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.
Attestation for brand_impersonation_detector-0.1.1.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 logA 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.