Undercurrent

Check any ship, company or person against sanctions-evasion research and the US, UK, EU and UN sanctions lists. Every answer comes with its source.

Built for journalists and researchers covering how Russia, Iran and others get around sanctions. An independent project.

Use it

https://undercurrent-research.vercel.app (the old undercurrent-jet-nine.vercel.app address redirects here)

Type a ship name, a seven-digit IMO number, a company or a person. New here? Press Follow one tanker for a five-step tour.

Each result shows:

• Our research: a dossier from the research snapshot, with sources.
• The official lists: US, UK, EU and UN entries, refreshed nightly.
• Wider check: OpenSanctions (95 sources).
• Connections: owners, managers and linked companies from the official lists, and US lobbying (firms, named lobbyists, agencies, bills) from lda.gov filings.

Stories: the shadow-fleet map, who lobbies (influence network and clean-names graph), semiconductors into Russia (routes, who reports, time to list, Kyrgyzstan and Kazakhstan), and how sanctions work.

Run it locally

npx serve .

Then open http://localhost:3000 (or the address serve prints). Everything works except the OpenSanctions check and the Connections panel, which run as Vercel Functions (api/search.js, api/connections.js) and show a link or "unavailable" when run this way.

How the data updates

Every night at 04:00 UTC, .github/workflows/update-lists.yml refreshes:

Data	Source	Where it goes
Official lists	US Consolidated Screening List, UK Sanctions List, EU financial sanctions list, UN Security Council list	data/lists/
Wider check	OpenSanctions bulk data (CC BY-NC 4.0, no key)	opensanctions.json.gz on the data-latest release
Connections	OpenSanctions relationship data	connections.json.gz on the release
Lobbying	lda.gov filings for the companies in data/lobbying-clients.json (add a company there)	lobbying.json.gz on the release
Semiconductors into Russia	UN Comtrade (HS 8542 exports to Russia, data availability), Eurostat Comext, OFAC SDN advanced XML, the Consolidated Screening List	stories/chips-into-russia/data/
Live graphs	The shadow-fleet map and the influence network, rebuilt from the official lists, the OpenSanctions OFAC and EU Official Journal exports (CC BY-NC 4.0) and the lobbying filings above	stories/shadow-fleet/network/ (fleet-data.json, nodes.json, edges.json), stories/who-lobbies/influence-network/kg.json, the day's changes in data/changes/changes.json (the Updates page), the page figures in data/site-stats.json, and data/live-graphs-meta.json

• Failure handling: each source fails alone. A source that fails to download, changes shape or shrinks by more than 20% keeps yesterday's copy, and a GitHub issue names it. The page says "Some lists may be out of date" when a list is stale.
• Live graphs: scripts/build_live_graphs.py runs after the other steps. If it keeps yesterday's map, or the lobbying asset is there but cannot be read (the map still updates and the network keeps yesterday's lobbying layer), it exits 1, and the nightly issue names "live graphs" and quotes the build's own note from data/live-graphs-meta.json. Its guards:
  • Source families: official links are counted per source family: the UK list, the US screening list, OFAC and the EU Official Journal (both via OpenSanctions) and the EU financial sanctions list. A family with 100 or more links yesterday that drops by more than 20% marks its government unavailable and the map keeps yesterday's copy. A smaller family is rejected only if it drops to none. The same holds if all official links together drop by more than 20%, or if the sample check fails (TASSOS, IMO 9408695, must keep its official link to Zulu Ships Management).
  • Empty files: both OpenSanctions downloads must arrive with rows. A UK, US or EU list that is not fresh, or a missing raw download, also keeps the previous map.
  • Write order: each file is first written whole to a .tmp file, then all are renamed into place in a fixed order: map payload, nodes, edges, network, page figures, then the change record, then the status file. The record is never ahead of the graphs it describes.
  • Change record: a source that kept its previous copy files no changes that day and is marked unavailable. The night it comes back reports what changed in it meanwhile. A re-run on the same day adds its changes to that day. History starts at the first live run.
• Chip firms: the list is hand-checked in stories/chips-into-russia/data/chips-firms.json. Firms are joined by OFAC id and each is named in a US Treasury press release. The home page's "months" figure is read from summary.json.
• Research snapshot: fixed at 25 September 2026 for search and the dossiers; the nightly build does not rebuild it. A hand rebuild with python3 scripts/build_research_index.py reads the map's 25 September files from git (commit ad46320), not the files the nightly rewrites, so it gives the same snapshot.
• Research notes: the Markdown files under stories/ are the source; the site serves the .html pages that python3 scripts/build_docs.py writes next to them. Edit the , run the script and commit both (a test fails if a page is out of date). redirects the old URLs.

Two jobs, one key

• build: downloads and parses all outside data with a read-only token and no secrets, then hands the results to publish as a short-lived artifact.
• publish: runs none of the project's Python. It:
  • rejects the artifact if it holds hidden files, links, or file names with anything but letters, digits, ., _, - and /
  • copies the expected files into place and attaches the release assets
  • commits to main only if the smoke check passed
  • opens the failure issue
• What publish may commit: a fail-closed allowlist limits it to plain .json files at the expected paths.
• The key: the deploy key NIGHTLY_DEPLOY_KEY lives only in the nightly GitHub environment, which only main may use. It is the repo's only deploy key, and the protect-main ruleset lets it push the nightly commit.

To replace the key, run this on your own machine (never paste the private key anywhere):

ssh-keygen -t ed25519 -N "" -C "undercurrent-nightly" -f ~/.ssh/undercurrent_nightly -q
gh repo deploy-key add ~/.ssh/undercurrent_nightly.pub -R Ttheegela/undercurrent --allow-write --title "nightly (environment)"
gh secret set NIGHTLY_DEPLOY_KEY --env nightly -R Ttheegela/undercurrent < ~/.ssh/undercurrent_nightly

Then run the workflow once (gh workflow run update-lists.yml --ref main), check both jobs pass, and delete the old deploy key.

Ask

A chat panel on every page that answers questions about what is on the site: the official lists, ship and company connections, lobbying, the semiconductor data, the research and the daily updates. An independent project, so it answers only from the site's own data and refuses anything else, including legal or compliance advice.

• How it answers: the model writes no sentences. api/ask.js runs it through OpenRouter (Claude Haiku 5.5, provider.data_collection: deny) for at most four rounds (ten calls in all) of lookups in api/_ask_tools.js, then forces one answer call. That call only cites evidence ids, each with a claim. api/_ask_check.js writes every sentence itself, either fixed copy filled from the cited items or one sentence copied word for word from a cited item. The fixed copy covers:

  • listings ("appears on the … list") and not-found lines ("not on the lists we check");
  • ages ("has been on the … list for 5 years 10 months (since …)", with what the date stands for, or "gives no listing date");
  • counts the tools compute: records on an official list under a programme, the research map's ships by programme group, list, flag, type or names (the research tool), and the chips research's firms, all of them or those based in one country;
  • records on an official list with a word in their names (check_lists with word: one word, its plural too, counted by record, examples newest first), the word printed only as the lists spell it and never as a listing or clean-bill word. A trailing S folds only from five letters and never after A, I, U or S, so BANK is BANKS but HAMAS is not HAMA. After the last sentence that cites the count or one of its examples comes the line that it matches the word as spelled, in names only, with no country or line of business;
  • the chips research's firms, one sentence each from the press release that named it ("US Treasury named … (China) on 30 Oct 2024."), newest release first;
  • nones that say what they rest on ("No programme on the … list is named …", "None of the ships in Undercurrent's research map …", "None of the N updates recorded … involve …" with how many could not be checked);
  • changes and source gaps, and "Showing N of M …" after a capped result, counting the matches the answer names and saying what they are (matching records, ships, records, firms or updates). A listing and its age are said once, as the age. An answer whose listings are all of one entity Undercurrent's research holds opens with the verdict its result page has ("TASSOS is listed by 3 of the 4 governments whose lists Undercurrent checks: …"), then says each government's listing once and its OpenSanctions entry, from every record of it in the evidence (a ship's records share its IMO number), so a listing the model did not cite is never left out.

  Anything it cannot build is dropped: the sentences it could build stand, followed by "I could only answer part of the question. Ask about each name on its own to check the rest.", and an answer with nothing left is a fixed fallback. When the model cites nothing after lookups that all worked, the answer is "Nothing recorded on this site answers that.", unless the daily updates record answered the question itself (no record before its first night, days no longer kept, tonight's run not made yet, no changes, or no update involving the topic): then the answer is that item's own line, with its caveats and source. The relevance gate (below) then drops sentences that don't bear on the question. Ask refuses nothing on its own (only the model can refuse, and then the answer is the fixed refusal), but an answer to a question that looks like a request for advice on doing business ends with a fixed notice that Ask gives no legal or compliance advice and that these are records with their sources. The system prompt is .

Variable	Where	Meaning
OPENROUTER_API_KEY	Vercel, Production, Secret	A dedicated OpenRouter key with a $5 limit that resets monthly. The owner enters it with vercel env add OPENROUTER_API_KEY production at the hidden prompt. It is never in the repo, a log, a test or a chat. Unset: POST /api/ask answers 503 disabled.
TYPESAFE_API_KEY	Vercel, Production, Secret	The relevance gate's TypeSafe key, separate from the eval one. The owner enters it with vercel env add TYPESAFE_API_KEY production. Read only in api/_ask_gate.js, never logged. Unset: answers are shown without the gate, and each logs the gate's fixed line.
ASK_PUBLIC	Vercel, Production	1 shows the Ask button on every page. Unset, the button stays hidden but the endpoint still answers, so the live evaluation can run against production before launch.

• Budget: the key's $5 monthly limit is the hard cap, and an OpenRouter guardrail gives the key a $1 daily budget under it. When the key's limit is spent OpenRouter answers 402 or 403, and Ask says it is resting until the key resets (the first of the next month, UTC, unless OpenRouter gives a date). When the daily budget is spent (a 403 from the guardrail) Ask says it is resting until the guardrail's reset day, and when the account has no credit (a 402 with no limit source) it says only that it is resting. The rest of the site is unaffected. Buy credits with auto top-up off. Each answered question, unless it is a follow-up, also makes one TypeSafe call for the relevance gate, outside this budget. A TypeSafe failure, a spent TypeSafe key included, fails open: the answer is shown unchecked.
• Cost estimate: the price is $0.10 / $0.50 per million input / output tokens (the spec's figure from OpenRouter's list, 19 Oct 2026, not re-checked). Every model call resends the system prompt, the tool definitions and all earlier tool results, so a question costs more the more it looks up. The token counts below are measured on the stubbed loop with the real site data and estimated at 3 to 4 characters per token (no tokenizer is available offline).
  • Typical question (one lookup, then the answer): 2 model calls, about 4,000 to 6,800 input tokens and 100 output tokens, so about $0.0007. $5 covers several thousand of these.
  • Worst case: a question that pulls the largest results (a one-word name such as "AL" returns about 14 KB) is capped at 10 tool calls in all and 5 model calls. The same lookup repeated ten times and spread to resend as much as possible (6, 2, 1, 1 calls, then the forced answer) resends about 500 KB in all: about 125,000 to 167,000 input tokens and at most 10,000 output tokens (2,000 a call, the model's reasoning included), so $0.018 to $0.022. $5 covers about 230 to 280 of these, and one visitor's 20 in an hour would cost about $0.35 to $0.43.
  • The relevance gate: each answered question, unless it is a follow-up, also makes one TypeSafe call, billed by TypeSafe for its input tokens (the question and the answer's sentences) and not in the figures above. A TypeSafe failure fails open: the answer is shown unchecked.
• Firewall: the rule that denies non-read methods on /api/ must allow POST on /api/ask only, and POST /api/search must still be refused.
• Live evaluation: node scripts/ask-live-eval.mjs --base https://undercurrent-research.vercel.app posts the evaluation questions to a deployed endpoint, prints each answer with its timing, and exits non-zero if any case fails. Its 59 questions are more than the endpoint's 20 an hour, so run them in the three --only batches it prints, an hour apart. With it also counts the declines: the fallback, and an answer that only says nothing recorded answers. It needs no key and costs a few cents. Run it before launch and after any change to the prompt or the model.

Evals

The 59 real-model questions in tests/ask-eval.json (the cases without "live": false) go through Ask's own loop and are scored in LangSmith, so how Ask does is on public record: the cases, the scores, the failures and the cost. 25 of them cover question patterns across the site's topics (counts, durations, topic filters on the updates, lists by programme, country or flag, records by a word in their names, questions whose honest answer is "none" or that nothing recorded answers, two-part questions and a near-miss name), each with a note on what a good answer would be. 8 more are the questions of a journalist test on the live site (26 Oct 2026): a ship's listings and their age, its owner and manager, why it was renamed, flags, the week's updates, a company on three lists, the chips firms in China, and what the dates and the data cannot show. Where the server can now say it (a count, an age, an undated listing, a none), the case expects that sentence in includes and no fallback. A live run meets that night's data and its own date, so an include holds only what neither can move:

• Fixed parts only: a count's sentence without its numbers, an age's head and its listing date without the span, no "Showing N of M" line, and no update's date. The chips median, which the nightly data recomputes, is the head of its sentence.
• Either shape: a question about recent updates takes the none line or a list of updates, whichever the night's record gives. An include can be a list of phrases, any one of which will do.
• Exact: listing sentences with their listing dates, undated listings, a programme no list names, not-found lines, quotes of the research and the explainers, and the day the record began.

tests/ask-eval.test.js checks every live include against these rules. A case accepts the fallback only where declining can be right. Each case's evidence is recorded once with Ask's real tools, from the committed data and the release assets (re-recorded on 22 Oct 2026 for the new claims; the word cases recorded on 24 Oct 2026, the journalist cases on 26 Oct 2026). It keeps its exact numbers, so the offline suite never changes with the nightly data.

Dashboard: (link added after the first run)

• What runs and when: .github/workflows/ask-evals.yml runs scripts/ask-langsmith.mjs.
  • Weekly: Mondays at 13:00 UTC, and by hand (gh workflow run ask-evals.yml --ref main). A run on main first makes the LangSmith dataset undercurrent-ask match the live cases, then runs them. Until a run on main, weekly or manual, has created the dataset, pull request runs fail with "dataset undercurrent-ask not found".
  • Per pull request: once, when it is opened or marked ready for review, if it touches Ask's code, prompt, cases or the runner. A pull request evaluates main's cases and never syncs the dataset, and the run records the pull request's own commit. Drafts and forks are skipped, and later pushes do not re-run it. A manual run on another branch does not sync either.
  • Comparing models: by hand only, with gh workflow run ask-evals.yml --ref main -f model=deepseek/deepseek-v4.1-flash. The same cases then run on that OpenRouter model (vendor/model; anything else stops the run before it starts) instead of the site's. The site itself keeps Claude Haiku 5.5. On main such a run also syncs the dataset, like any manual run there.
  • Repetitions: by hand only, with -f repetitions=3 (1, 2 or 3; the runner's --repetitions N, which only a manual run takes). Every case then runs that many times in the one experiment, as that many runs of the set; they are not retries. The job has 45 minutes for that.
• Experiments: named ask-weekly-…, ask-manual-… and ask-pr-<number>-…, with the model's name added when a run compares another model (ask-manual-deepseek-v4.1-flash-…). Each carries commit, trigger, pr, model (the model the run used), judge_model (jev-latest, or null when the relevance judge was skipped) and prompt_hash (the first 12 characters of a hash of the system prompt and the tool definitions), so a change in score can be tied to a change in the prompt.
• Outcomes: each case ends as one of four. quality: Ask answered. unavailable: Ask replied that it is unavailable. budget: the eval key's limit was reached. download_failed: a lookup could not download its data (this wins over quality).
• Scores: pass is recorded only for quality outcomes, so the pass rate leaves infrastructure out. It is 1 when the answer is the expected kind, says nothing the case rules out, and every sentence is grounded in what the lookups returned. On every case: , , , , , and (the input tokens TypeSafe billed for the relevance gate, also in the case's trace outputs; 0 when the gate ran without a key). On answered cases: and, where the case lists sentences the answer must contain, . There are no retries: a case runs once in each run of the set, as a visitor would have met it.

Security

• Headers: set in vercel.json and enforced.
  • Content-Security-Policy: strict for the app, looser for /stories/, which has inline scripts and pinned CDN libraries with integrity hashes.
  • Also: X-Content-Type-Options, X-Frame-Options: DENY, Referrer-Policy, Permissions-Policy, Cross-Origin-Opener-Policy.
  • HSTS comes from Vercel.
• Firewall: set in the Vercel dashboard, not in this repo.
  • /api/ is rate-limited to 120 requests a minute per IP.
  • Any method other than GET, HEAD or OPTIONS is denied. Ask's launch adds one exception (see Ask).
• APIs: answer GET only; the one exception is POST /api/ask (see Ask). Queries over 200 characters are rejected with 400, and so are names that normalise to under two characters.
• Data: the sanctions side names people only as official lists or government documents name them. Lobbyists are named only from their own US lobbying filings. Names in exclude_lobbyists (in data/lobbying-clients.json) are never shown. Corrections and removal requests go through GitHub issues, as described on the About page.

Monitoring

UptimeRobot checks three things every 5 minutes and emails on failure:

• the home page
• /api/search?q=tassos, which must contain "enabled":true
• /api/connections?imo=9408695, which must contain "matched":true

Public status page: https://stats.uptimerobot.com/5FeFn9Euy7

A scheduled maintenance agent checks the nightly run every day at 10:30 UTC and opens fix PRs; changes to listing or naming rules, workflows or security settings wait for the owner.

Hosting is Vercel's free Hobby plan. It has no billing, and Vercel pauses the site rather than charging if usage limits are reached.

Tests

python3 -m pytest -q scripts && npm test && npm run smoke

Credit

The research comes from the VeilTrace team at the Trace the Unseen build day, 25 September 2026: https://github.com/Ttheegela/veil-trace

Code is MIT licensed. Data keeps its sources' terms; see stories/about-the-data.html.