Core documentation

HECAVEX Radar technical reference

Architecture, source behavior, public schemas, operating requirements, and data terms for the open-source Radar deployment. Detection methodology is documented separately on the Methodology page.

Architecture

Python pipeline, static viewer

The browser has no application server, account system, or database connection.

01
Collect
Bounded Python collectors read passive certificate events and existing public reports.
02
Archive
Validated, defanged source observations are stored in date-partitioned NDJSON.
03
Synchronize
The publisher revalidates, scopes, merges, limits, sorts, and atomically writes radar.json.
04
Render
A static React application validates the snapshot structure and renders read-only controls.

Publication boundary

Only synchronization writes the public snapshot. An unavailable optional source cannot erase healthy-source data, and an unexpected sharp reduction is blocked unless an operator explicitly authorizes a reset.

Sources and provenance

Three public observation labels

Only normalized observations that pass the publication boundary become dashboard rows. Transient search hints can trigger investigation, but cannot create or label a row by themselves.

Certificate names

CertStream

Emits Certificate Transparency updates over a websocket. Radar reads DNS names, rejects official domains, applies its public matcher, and archives qualifying candidates without retrieving those domains.

Provider documentation

Existing public scans

URLScan

Authenticated passive searches require public visibility in both the search summary and result detail. Exact-domain, brand, title, and primary-document hash pivots remain bounded and independently validated.

Provider documentation

Optional deployment input

HECAVEX

A deliberately limited public JSON export can be configured over HTTPS. Every record passes the same normalization, brand scope, evidence, timestamp, and size checks before it can appear publicly.

HECAVEX

Search hints only

Transient discovery inputs

Bounded third-party lists are processed in memory and can trigger exact passive URLScan lookups. Raw rows are not archived, do not publish directly, and never appear as public source labels.

Attribution and terms

Coverage is intentionally incomplete

CertStream observation is sampled. URLScan is queried only for existing public reports; no result is unknown, not benign, and does not suppress an independently qualifying CertStream candidate. HECAVEX is optional. None of these inputs provides a continuous-monitoring guarantee.

Public data catalogue

Deliberately published datasets

These resources are intended for defensive use and public retrieval. Candidate links remain defanged; raw provider inputs, credentials, private observations, and quarantined material are not part of this catalogue.

Current snapshot · JSON

Radar signal snapshot

The generated dashboard input contains the current schema version, generation time, bounded recent signals, and per-source archive-read state. It is crawlable because it is advertised as the Dataset distribution.

Download radar.json

Reviewed registry · JSON

Lithuanian brand registry

Reviewed aliases, opt-in fuzzy aliases, official domains, collision exclusions, and supporting references used by the public matcher. Repository history records changes and review context.

Open the registry

Latest attempt · JSON

CertStream collection health

Actual start, end, websocket listening seconds, aggregate input and match counts, outcome, schedule delay, last success, and freshness. It contains no certificate names or unpublished candidates.

Download collection-health.json

Freshness

Consumers must read generatedAt and each source's fetchedAt and state. A source timestamp is an archive-read time. CertStream connection evidence is reported separately in the bounded collection-health document and still does not prove continuous coverage.

Public data contract

Snapshot schema version 1

The Python publisher is normative; browser validation is an additional structural check.

{
  "schemaVersion": 1,
  "dataset": "live",
  "generatedAt": "2026-08-21T09:15:00.000Z",
  "signals": [],
  "sources": []
}

Public timestamps use canonical UTC millisecond form. Before publication, retained and newly collected rows are checked against the current Lithuanian brand registry; official hosts, unresolved brands, exclusions, and conflicting brand mappings are dropped.

Signal fields

Field	Type	Meaning
`id`	string	First 20 hexadecimal characters of SHA-256 over the normalized defanged hostname.
`url`	string	Defanged HTTP(S) indicator. Userinfo is rejected; query and fragment are removed; unsafe paths are redacted.
`domain`	string	Defanged normalized hostname.
`firstSeen`	UTC timestamp	Earliest accepted observation in canonical millisecond form.
`lastSeen`	UTC timestamp	Latest accepted observation in canonical millisecond form.
`sources`	string[]	Deduplicated providers: CertStream, URLScan, or HECAVEX.
`status`	enum	active, suspected, offline, mitigated, or unknown.
`brand`	string \| null	Registry-resolved claimed target; this is not actor attribution.
`country`	string \| null	Hosting observation, not an actor location.
`host`	string \| null	Provider/ASN text or a defanged address.
`screenshotUrl`	string \| null	Optional HTTPS screenshot on exactly urlscan.io.
`referenceUrl`	string \| null	Optional canonical public URLScan result URL.
`hashes`	string[]	Up to eight lowercase SHA-256 hashes of primary HTML response bodies.
`confidence`	integer	Rounded and clamped score from 0 to 100; not a probability.

Archive schema 1

CertStream NDJSON

Stored under data/certstream/YYYY-MM-DD/domains.ndjson. Each row carries observed time, defanged and registrable domains, brand, confidence, and bounded public scoring reasons.

Archive schema 2

URLScan NDJSON

Stored under data/urlscan/YYYY-MM-DD/signals.ndjson. Typed brand evidence can be domain, title, verdict, or supplemental primary-HTML-hash provenance; a hash alone cannot bind a brand.

Optional input

HECAVEX JSON

Accepts an array or an object containing signals. Alternate common field names are normalized, supplied source labels are ignored, and hashes require explicit primary-HTML SHA-256 typing.

Merge rules

One public row represents one normalized host. The publisher unions sources and hashes, keeps earliest and latest timestamps, selects the most specific safe path, keeps the highest confidence, and rejects conflicting brands.

Operations and deployment

Scheduled GitHub Pages publication

Schedules are UTC and can start late. Manual dispatch remains available for collection, sync, and deployment.

Workflow	Trigger	Result
Continuous integration	Pull requests and relevant pushes	Lint, type checks, tests, and production build
CertStream collection	02 and 32 minutes past each UTC hour	Candidate archive and latest public attempt health
URLScan hunt	03:37 and 15:37 UTC	Vilnius-date validated URLScan archive
Snapshot synchronization	17 minutes past each UTC hour	Validated public radar.json snapshot
Pages deployment	After verified main changes or manual dispatch	Static GitHub Pages artifact

Scheduled does not mean observed

CertStream is scheduled for 48 four-minute windows per day: 192 minutes, or at most 13.3% of wall-clock time. Actions can start late or fail. The dashboard reads actual timing, aggregate counts, outcome, schedule delay, last success, and freshness from collection-health.json; those fields remain separate from archive-read state in radar.json.

Source-state semantics

State	What it establishes
`healthy`	The snapshot publisher read that source archive successfully. Zero records is a valid empty result.
`partial`	The latest archive refresh was incomplete. A shown timestamp can identify the previous successful read, and recent rows may be retained.
`skipped`	An optional deployment input was not configured or attempted.

Healthy-empty example: the successful run reviewed on 21 August 2026 listened for 240 seconds and processed 83,875 messages containing 146,591 DNS names, with zero qualifying matches. That is evidence of one healthy empty run—not continuous coverage. The dashboard now presents the latest bounded attempt directly; repository operators can still inspect complete execution logs in GitHub Actions.

Repository configuration

Setting	Kind	Purpose
`URLSCAN_API_KEY`	Secret	Required only for passive URLScan search and result retrieval.
`CERTSTREAM_URL`	Secret or variable	Optional monitored WSS endpoint; otherwise the scheduled workflow starts its pinned temporary source.
`HECAVEX_ENABLED`	Variable	Enables the optional configured public HECAVEX export.
`HECAVEX_FEED_URL`	Secret	Required with HECAVEX enabled; production endpoints must use HTTPS.
`HECAVEX_FEED_TOKEN`	Secret	Optional read-only bearer credential for the configured export.

Local development

Python 3.12 · Node 22.12 · pnpm 10

python -m pip install -e ".[dev]"
corepack enable
pnpm install
pnpm dev
pnpm check

Custom domain

radar.hecavex.com

GitHub Pages uses a CNAME record named radar pointing to hecavex.github.io. The organization domain-verification TXT record should remain in DNS, and HTTPS is enabled after validation.

Safety controls

Untrusted input throughout

Credentials stay in Actions secrets, workflow permissions are minimal, external Actions are commit-pinned, output paths are repository-bounded, and source/archive sizes and record counts are capped.

Durable CT coverage decision

Stage 02 will use checkpointed CT-log/API polling and backfill as the durable coverage source, while retaining CertStream for low-latency discovery. The current sampled workflow remains in place until that implementation is tested. Read the architecture decision record.

Security and maintenance

Maintained on a best-effort basis

Radar is an open research project, not a 24/7 SOC, incident-response service, brand-monitoring contract, notification service, takedown provider, or availability SLA.

Maintenance state

Active · best effort

Automated workflows publish when their validation gates pass. Source-panel state and snapshot timestamps expose what the current data can establish; workflow history remains the operational source of truth.

Review workflow history

Responsible reporting

Security and sensitive data

Do not open a public issue for vulnerabilities, credentials, victim data, or sensitive indicators. Use the published security contact and avoid contacting a suspected phishing host while reproducing a problem.

Open security.txt

Data quality

False positives and corrections

Report a mistaken listing, brand mapping, unsafe value, attribution issue, or removal request by email. A listing is always a research lead rather than a public accusation.

Report a false positive

Project source

Review and contribution

Source, tests, workflows, registry references, and issue history are public. Contributions must preserve defanging, passive collection boundaries, evidence provenance, and conservative publication rules.

Open the repository

Data terms and attribution

Software licensing does not relicense data

Apache License 2.0 covers original Radar software and documentation. Third-party observations, trademarks, screenshots, and source material retain their own rights and conditions.

Certificate Transparency

Certificate observations are public CT facts. The scheduled server component retains its separate MIT license and upstream terms.

URLScan

Report metadata, screenshots, and hashes remain subject to URLScan terms and depicted-site rights. Authentication does not itself grant redistribution rights.

URLScan terms

PhishDestroy

Primary Active is used only as a transient discovery seed under its MIT license. Raw list rows are not copied into Radar archives.

Upstream project

CERT Polska

The active Warning List is used only as a transient discovery seed under the processing permission stated by its public API specification.

Warning List

HECAVEX export

The exporter remains responsible for excluding private history, proprietary evidence, credentials, personal data, and material it cannot publish.

Brand registry

Names and domains identify their owners and do not imply endorsement. Registry entries cite authoritative public sources.

Report a false positive, sensitive value, attribution problem, or removal request to info@hecavex.com.

Python pipeline, static viewer

Collect

Archive

Synchronize

Render

Three public observation labels

CertStream

URLScan

HECAVEX

Transient discovery inputs

Deliberately published datasets

Radar signal snapshot

Lithuanian brand registry

CertStream collection health

Snapshot schema version 1

Signal fields

CertStream NDJSON

URLScan NDJSON

HECAVEX JSON

Scheduled GitHub Pages publication

Source-state semantics

Repository configuration

Python 3.12 · Node 22.12 · pnpm 10

radar.hecavex.com

Untrusted input throughout

Maintained on a best-effort basis

Active · best effort

Security and sensitive data

False positives and corrections

Review and contribution

Software licensing does not relicense data

Certificate Transparency

URLScan

PhishDestroy

CERT Polska

HECAVEX export

Brand registry