Hawkeye Sterling - Entity Risk Assessment (RA)
A static web application for AML/CFT customer (entity) risk assessment, built for Dealers in Precious Metals and Stones (DPMS) and adaptable to other reporting entities.
Live site: https://hawkeye-sterling-ra.netlify.app. Availability alone does not prove that the current main commit is published. See Site Currency below.
Project: Contributing · Security · License · Support · Roadmap
Technical & compliance: Architecture · Methodology · Coverage · Data Sources · Governance · AI Governance · ISO 42001 Controls (Provisional) · Operations · Documentation
Live verification and assurance
How to read this dashboard: Each badge shows the latest result of its linked GitHub workflow, not an overall compliance verdict. A green workflow is not sufficient evidence that its underlying control passed. Red, cancelled, pending and unverified controls must never be counted as green. Check the required evidence in the right column and the linked run before interpreting any result.
Acceptance rule: All mandatory controls must be substantively verified at the same current-code checkpoint. CI, security scan wrappers, screening dispatches and provider probes cannot substitute for their required evidence. The table deliberately preserves real failed statuses rather than displaying a cosmetic all-green result.
Mandatory control verification
| Control | Live workflow badge (not an assurance verdict) | Evidence required for PASS |
|---|
| Worldwide screening assurance | | Persisted receipt must independently verify current-commit source quality |
| Sanctions case screening | | Completed authorized customer and employee screening, with run receipts |
| Control freshness | | All mandatory scheduled controls have successful runs within cadence |
| Screening recovery | | Evidence-backed recovery, not merely accepted workflow dispatches |
| Advisor guardrails | | Completed real-provider behavior tests without evaluation errors |
| Advisor bias assurance | | Completed real-provider bias tests without evaluation errors |
| Production publishing | | Netlify actually publishes the requested commit, not just HTTP 200 from a hook |
| Production code parity | |
Screening scope is not screening assurance. Configuration targets a 195-country subject universe. The generated coverage figures and country-depth register describe configured sources and geographic applicability, not successful retrievals or clean screenings. The independent runtime receipt is authoritative for observed evidence. A domain's operational flag does not imply sourceQuality.assured; if sourceQuality.assured is false, independent screening assurance is degraded even when a runtime step passed.
More checks: All GitHub Actions · Semgrep · Gitleaks · Bandit · OSV dependency scanning · Dependency Review · Workflow lint · Cross-browser smoke · PEP harvest · Regulatory Watch · Delivery Watchdog
Contents
The command-center suite
A dark neon, AI-persona "command center" spanning three sibling pages - pure HTML/CSS/JS, no framework, cross-linked from the header nav and sharing the six robot portraits in assets/:
| Page | File | Purpose |
|---|
| Entity Risk Assessment | index.html | The primary tool - live 0–30 risk scoring, animated gauge, CDD/SDD/EDD verdict, analyst override, Risk-Data editor, register and activity log. |
| AI Operations Console | console.html | A live monitoring HUD - a robot "analyst on duty" inside an animated radar, an operator switcher, count-up stat tiles, a live alert stream, the diligence mix and a jurisdiction watch. |
| Hawkeye Sterling Advisor | advisor.html | A cited-answer AML Q&A - a question composer with a swappable AI persona that returns a verdict, cited legal basis, decision guide and recommended steps, plus a filterable regulatory Q&A. |
The AI Risk Advisor in the assessment sidebar is a robot whose head and HUD colour follow the operative outcome - Vale (teal) for CDD, Cypher (amber) for SDD, Ember (red) for EDD / PROHIBITED - each with a one-line advisory note. The header carries a persona avatar, a live UTC clock and a lock toggle. Every animation (gauge draw-in, radar sweep, HUD spin, entrance) respects prefers-reduced-motion.
Screenshots
Desktop captures of the three screens (Chromium, 1280×900 - sources in docs/screenshots/):
| Entity Risk Assessment | AI Operations Console | Hawkeye Sterling Advisor |
|---|
| | |
Features
- Structured risk scoring across jurisdiction, business activity, onboarding channel, operational history, relationship duration, ownership/control/compliance questions, and supply-chain material sources (recycled and mined).
- Risk data maintenance - a built-in Risk Data panel where the compliance officer can override any country, activity, or material score (and the FATF call-for-action flag) on top of the firm-approved baseline. Every override requires a reason, is date-stamped, flags the affected factors in the live breakdown and the printed report, and can be exported/imported as a shared "risk data sheet" file or reset to baseline.
- Dark neon interface - six numbered form sections beside a sticky risk-summary sidebar: an animated 270° SVG risk gauge, the required-diligence verdict with threshold chips, a 0–30 risk-position bar, and a collapsible per-factor score breakdown. Entrance and gauge animations respect
prefers-reduced-motion.
- Live verdict - total score, numeric band (CDD / SDD / EDD), and boundary warnings one point below each band edge, recomputed on every change.
- Hard outcomes - designated-party exposure (sanctions on the entity or its principals, terrorist financing, proliferation financing) produces a PROHIBITED - Do Not Onboard verdict with freeze-and-report instructions; PEP exposure, FATF call-for-action jurisdictions, and the ASM/high-risk-country red flag force mandatory EDD regardless of the numeric score. Every escalation is shown with its reason and carried into the export and printed report.
- Analyst override - the operative outcome can be raised above the computed one (one-way ratchet: CDD → SDD/EDD, SDD → EDD) with a mandatory justification that prints on the report; it never weakens the computed outcome and never applies to prohibited relationships.
- Screening evidence - record the system/provider, date, and reference ID for sanctions, PEP, and adverse-media checks; printed in the report as audit evidence.
- Assessment metadata - auto-generated reference (
RA-YYYYMMDD-NNN), assessment date, assessor name and role.
- Expanded entity identification - legal and trading names, registration/licence number, jurisdiction, registered address, website/email, principals (beneficial owners / controllers / directors).
- Analyst notes & rationale - free-text section included in the printed report, with a one-click Narrative Template that writes a formal, plain-language risk rationale for the matching band (low / medium / high / prohibited), citing the Company's policies by full name (Risk Assessment methodology, Know Your Customer, Risk Appetite Statement, Targeted Financial Sanctions) and filling in the entity, date, and score automatically.
Automated daily screening engine + AI layer
Beyond the on-device assessment tool, the repository runs an automated, audit-grade
daily screening engine (screen.py) over the firm's live customer base,
augmented by a governance-first AI layer (ai.py). It is free to run -
no paid data feed and no API key are required; an LLM is strictly optional and opt-in.
One unified daily report (workflow weekly-adverse-media.yml,
RUN_MODE=unified) screens every company and every recorded owner / director / UBO
through three modules in a single pass and posts one MLRO-ready task to Asana, delivered
by 09:00 UAE:
| # | Module | What it does |
|---|
| ① | Sanctions / watchlists | Fuzzy name-match against the live OFAC SDN · UN · EU FSF · UK OFSI · UAE EOCN lists (plus Canada SEMA as a best-effort supplementary list). Shows every candidate with the matched entry and score. |
| ② | Adverse media | Google News RSS across 5 locales (US/GB/AE/TR/AR) plus a targeted risk-term query, the GDELT global index, and Bing News RSS (a third, independently rate-limited pool - headline recall now needs three simultaneous feed refusals to go dark); duplicate stories merged across outlets, bucketed by typology, ranked recent-first, every item carrying its real article link. A deterministic fourth net - the OpenSanctions crime watchlist (bulk download, matched locally) - keeps adverse-exposure coverage alive even when every news feed rate-limits the CI runner. |
| ③ | PEP | Auto-detected against Wikidata (no list supplied by the firm) - politicians, judges, military/SOE heads and their relatives & close associates (RCA). Rate-gated with a circuit breaker; when Wikidata is unreachable, the OpenSanctions PEP mirror (bulk) re-covers the affected individuals, provenance-marked. |
Screening intelligence
- False-positive suppression - a decisive second match on the distinctive name "core" after stripping corporate/legal boilerplate, so two firms sharing only suffixes don't match.
- Ownership / control (50 % rule) - when an owner/UBO matches a designation, the company is flagged by control linkage even if its own name is clear.
- Delta engine - each report leads with what is new since the last run; standing items are marked, never dropped (state in
data/screen-delta-state.json).
- Transliteration recall - Arabic/Turkish spelling variants (Mohammed/Muhammad, Abdul/Abdel, bin/ibn …) widen sanctions matching.
- MLRO case subtasks - each new hit becomes an assigned Asana subtask with a disposition to set.
- Onboarding screen (
onboarding-screen.yml) - screens newly-added customers every 6 h, not only in the daily batch.
- Degrade loudly - a run that cannot screen never reports all-clear; reduced coverage is shown, and the
freshness-check raises a loud alarm if a mandatory-daily control fails to run.
AI layer (ai.py) - adopted in line with the UAE National AI Strategy 2031, governance-first:
- Customer risk rating (Low / Medium / High) with explainable factors + EDD cadence (FATF R.10).
- Adverse-media triage - severity · relevance · confidence per article.
- Related-party / network detection - shared owners/UBOs surfaced across the book.
- goAML STR/SAR draft - drafted for HIGH-risk/confirmed cases; a human always reviews and files.
- AI decision-support summaries - "why flagged / what to check" per alert.
AI governance & security (see docs/AI-GOVERNANCE.md)
- No hallucinations / no fabricated data - filed reports contain only real, sourced data; every item traces to a real list entry, article link, or Wikidata record.
- LLM is opt-in & bounded - gated behind
ANTHROPIC_API_KEY. With no key the engine runs fully on-runner, deterministic, with no data egress. When enabled, the LLM is used only for grounded classification (adverse-media triage); generative report prose stays off unless REPORT_ALLOW_LLM=1 is explicitly set.
- Prompt security (UAE "Securing Agentic AI") - all fetched web text is treated as untrusted: sanitized, wrapped, and screened for prompt-injection; a detected attempt never reaches the model and is flagged in the audit trail.
- Human-in-the-loop - nothing decides, freezes, or files; the MLRO does. Every run is retained 10 years (Asana + GitHub Actions).
Agentic operating model (agents.py) - aligned to the UAE "Sovereign AI" model (People → Agents → Workflows → Decisions → Outcomes; humans set direction, governance keeps outcomes aligned):
- Agent identity & least-privilege authorization - each module is an agent with an explicit action allow-list; the orchestrator records every action and denies anything outside it (e.g. the case agent may propose drafts but never file; only the delivery agent may write to Asana; no agent holds decision authority).
- Runtime credential scoping - a credential broker hands a secret to an agent only if it is authorized for an action that needs it; every grant/denial is logged and the secret value is never recorded (presence is masked).
- QA / governance gate - before publish, a deterministic gate verifies degrade-loudly, that every finding carries its source, that no prompt-injection item was model-classified, and that every flagged subject has a risk rating; failures surface as ⚠ ATTENTION in the report, never silently passed.
- Observability - the report's §⑥ Agentic Operating Model prints the full agent audit trail + QA gate + credential-scoping summary for every run.
Sanctions coverage by country
data/sanctions-country-coverage.json records all 195 countries. Each row has its national-list status and a baseline of lists that already cover it every day:
- UN Security Council Consolidated List: screened daily and binding on every UN member state (193 rows carry
UN).
- EU consolidated financial-sanctions list: screened daily and directly applicable in the 27 EU member states (27 rows carry
EU). An EU member without its own national list is therefore still covered for EU-level sanctions; only a separate national list, where one exists, is additional.
- US OFAC and the UK Sanctions List: also screened daily. Their designations reach many targets worldwide, including in Latin America and the Caribbean, but they are those issuers' lists, not a country's own, so they are not recorded as
baseline.
FATF black and grey lists
data/fatf-assessments.json holds the FATF lists from the 19 June 2026 statements (Paris plenary, 17–19 June 2026), with each jurisdiction's assessment: its FSRB, when it made its high-level political commitment, its MER adoption date where the statement gives one, its action-plan status, and the action-plan items quoted verbatim.
- Black list (High-Risk Jurisdictions subject to a Call for Action), 3 jurisdictions: DPRK and Iran (call for countermeasures); Myanmar (call for enhanced due diligence).
- Grey list (Jurisdictions under Increased Monitoring), 22 jurisdictions: Angola, Bolivia, Bosnia and Herzegovina, Bulgaria, Cameroon, Côte d'Ivoire, Democratic Republic of the Congo, Haiti, Iraq, Kenya, Kuwait, Lao PDR, Lebanon, Monaco, Nepal, Papua New Guinea, South Sudan, Syria, Venezuela, Vietnam, Virgin Islands (UK) and Yemen.
- The FATF found that Bulgaria, Côte d'Ivoire, the DRC and Monaco had substantially completed their action plans, which warrants an on-site assessment. Algeria and Namibia were removed in June 2026.
The register's fatf field marks each listed country, and the MCP server serves the file as hawkeye://reference/fatf-assessments. A test fails if this file, the register and the risk-scoring list data/jurisdiction-risk.json disagree. Update all three after every FATF plenary (February, June and October).
Other public country indicators (context, not scored)
data/country-indicators.json adds three public-source country indicators next to a screening hit's jurisdiction in the daily report ("Country context (not scored)"), and the MCP server serves it as hawkeye://reference/country-indicators:
- US INCSR major money-laundering jurisdictions: the 80 jurisdictions in the 2025 INCSR Volume II (March 2025).
- US Trafficking in Persons tiers: the 2025 TIP Report tier placements; only Tier 2 Watch List and Tier 3 are shown.
- EU list of non-cooperative jurisdictions for tax purposes: the 10 Annex I jurisdictions adopted by the Council on 17 February 2026.
These never change the risk score; the FATF list above stays the only jurisdiction scoring input. Commercial country reports (KnowYourCountry, the Organized Crime Index) restrict redistribution, so they are linked, never copied: under the jurisdiction select the app links each country's KnowYourCountry AML profile and, for the 193 UN member states, its Global Organized Crime Index profile. The OC Index report is "all rights reserved" and its downloadable dataset states no reuse licence, so no Index score is stored or used in scoring.
OC Index 2025 country-research catalog: data/ocindex-2025-references.json records the publisher's 2025 downloads and methodology, plus the filename inventory of 192 conventionally named country PDFs from the supplied archive. The archive also contains a separate 3-page Word-generated turkiye.pdf, not the original published report; the catalog points to the publisher's official Türkiye PDF instead. The 2025 Index assesses 2024 conditions, including organized-crime markets, actors and resilience. This evidence is analyst-reviewed context only, never an extra sanctions list, Google News/GDELT substitute, automated customer risk-score input, MLRO decision or screening-assurance PASS. No PDF contents are redistributed.
The same file also holds each jurisdiction's FATF effectiveness ratings (the 11 Immediate Outcomes) for the 199 jurisdictions in FATF's consolidated assessment ratings (2013 Methodology table updated 24 August 2026; 2022 Methodology table updated 25 September 2026). FATF licenses this data under CC BY 4.0, and the file carries FATF's citation and adaptation notice.
Suggested country score (draft, pending MLRO approval)
scripts/country-score.mjs computes a second, reproducible 1-3 score for every country and writes it to data/country-score-suggested.json. The app shows it under the jurisdiction select and the daily report prints it next to a hit's jurisdiction, beside the current score. It is never applied: no scoring code reads it, and changing a country's score stays an MLRO decision through the existing override (a reason is mandatory).
| Factor | Effect |
|---|
| FATF call for action (black list) | suggested 3 |
| FATF grey list | suggested 3 |
| FATF effectiveness: Immediate Outcomes rated High or Substantial | 0-1: 3 pts, 2-3: 2 pts, 4-6: 1 pt, 7-11: 0 |
| US INCSR major money-laundering jurisdiction | 2 pts |
| US TIP Tier 3 / Tier 2 Watch List | 2 pts / 1 pt |
| EU tax list Annex I | 1 pt |
Points give 0-2 = 1 Low, 3-5 = 2 Medium, 6-8 = 3 High. A jurisdiction FATF has not rated, and that is not FATF-listed, gets no suggestion. The weights were chosen when the method was proposed; no source sets them. Transparency International's Corruption Perceptions Index was proposed but is left out because TI's terms (CC BY-ND 4.0, no commercial use) do not allow it here. The method has no sanctions factor yet, so a suggestion below the current score is not a recommendation to lower it. npm test fails if the committed file drifts from its inputs (node scripts/country-score.mjs --write regenerates it).
On 2026-10-08 the 17 suggestions above the then-current score were applied to the country list, on the approval of Luisa Fernanda (repository owner); no separate MLRO countersignature is recorded. The 53 lower suggestions were not applied: 39 of them would take a country off score 3, which also switches off the OECD Annex II escalation for artisanal (ASM) gold from that country.
Gold trade-route monitoring and PEP coverage QA (review-only)
The transaction-monitoring engine includes explicit gold trade evidence rules:
GOLD_ROUTE_DEVIATION compares the recorded planned and actual transport
routes (ordered two-letter country codes); GOLD_ROUTE_CHANGE reports an
expressly documented post-contract shipment-route or consignee change;
GOLD_ORIGIN_UNVERIFIED reports an explicitly failed/unverified origin
check. A malformed supplied route gives GOLD_ROUTE_UNREADABLE, which needs
manual checking. An absent route or unknown origin is not treated as proof
of a mismatch or a clean supply chain. All are MLRO review findings, not
sanctions designations, fraud findings, reporting/freeze instructions or
automatic customer decisions.
A Payments Register template can provide Gold trade: yes,
Gold planned route: GH, AE, Gold actual route: GH, TR, AE,
Gold route changed after contract: yes, and
Gold origin verified: no. Corresponding fields are also documented
in data/transaction-feed.schema.json. Production transaction
monitoring remains inactive without an approved real feed. Never
commit actual transaction or shipment/customer PII to this repository.
The existing hawkeye_analyze_kyc_note MCP tool also returns an
individuals[].pep_country_qa reminder for Turkey (including Türkiye
spelling), India and Papua New Guinea. These are operator-selected
screening-quality spot-check examples, not newly elevated country risk
scores or evidence of PEP exposure. A nationality never establishes a PEP
finding, and a negative public-source match never confirms someone is not a
PEP. No country scores, lists or Asana KYC records change.
The 53 proposed country-score decreases remain unapplied. In
particular, 39 would lower a high-risk classification and affect the
existing artisanal-gold EDD trigger. Such changes need separate documented
risk-model validation and MLRO approval, not this engineering PR.
MCP server (AI-agent access to the engine)
A Model Context Protocol (MCP) server exposes the deterministic screening
engine - sanctions/watchlist name screening, transaction monitoring, KYC/CDD gap
analysis, jurisdiction-risk tiering, transliteration-variant expansion,
adverse-media keyword scanning and DRAFT STR-dossier assembly - as MCP tools,
resources and prompts an AI agent (Claude Desktop, an SDK client, the MCP
Inspector) can discover and call. MCP is the open standard that connects an AI model to external
tools through one uniform interface; this server is the bridge between an agent
and the engine that already powers the daily screening workflow.
- Zero new dependencies. The stdio transport (newline-delimited JSON-RPC 2.0)
is implemented in the Python standard library - no
mcp/FastMCP install,
nothing added to ci/requirements.txt, no new supply-chain surface.
- Decision-support only. Every tool is read-only, deterministic and offline;
nothing onboards, files or freezes - an MLRO adjudicates every result.
- Untrusted input. Tool arguments come from an LLM and are type-checked and
size-capped at the boundary before reaching the engine.
pip install --require-hashes -r ci/requirements.txt # engine runtime deps
python3 mcp_server.py # serve on stdio
Files: mcp_server.py (transport), mcp_tools.py
(engine wrappers), test/mcp_tools_test.py (tests,
wired into CI). Full reference: docs/mcp-server.md.
Risk methodology
Scored factors
| Factor | Scoring |
|---|
| Jurisdiction of incorporation & operation | Per-country score (1 Low / 2 Medium / 3 High) from the embedded country list |
| Nature & complexity of business activities | Per-activity score (Regulated Financial Entities = 1; trading, mining, refining, jewellery, wholesale/pawn = 3) |
| Ownership, control & compliance (11 questions) | Yes = 3, No = 1 - except AML/CFT control adequacy, which is inverted (Yes = 1, No = 3) |
| Onboarding channel | In-person = 1, Remote / non-face-to-face = 3 |
| Operational history & relationship duration | < 1 year = 3, 1 year = 2, 2+ years = 1 |
| Supply chain - recycled sources (×3 suppliers) | Per-material score 0–3 (e.g. LBMA Good Delivery = 1, gold-processing chemicals = 3) |
| Supply chain - mined sources (×3 suppliers) | LSM / MSM = 2, ASM (artisanal) = 3, N/A = 0 |
Numeric risk bands
| Total score | Band | Outcome | Suggested review cycle |
|---|
| 0–19 | CDD | Customer Due Diligence | 12 months |
| 20–22 | SDD | Simplified Due Diligence review | 6 months |
| 23+ | EDD | Enhanced Due Diligence | 3 months |
Review cycles follow the firm's Know Your Customer procedure: low-risk customers are reviewed at least every 12 months, medium-risk every 6 months, and high-risk at least every 3 months with EDD.
Hard outcomes (override the numeric band)
The numeric score is always displayed unchanged; the operative outcome is layered on top, in strict priority order, with every reason shown in the banner, the JSON export, and the printed report.
1 · PROHIBITED - Do Not Onboard. A Yes on any designated-party question ends the assessment: do not onboard, freeze funds where held, and file a report with the FIU / relevant authority. No review date is suggested - the relationship is declined.
- Sanctions - beneficial owners, controllers, directors, or senior management
- Sanctions - the legal entity itself
- Terrorist financing connections
- Proliferation financing connections
2 · Mandatory EDD floor. When not prohibited, any of the following forces EDD regardless of the total score:
| Trigger | Basis |
|---|
| PEP exposure = Yes | FATF Recommendation 12 |
| Jurisdiction on the FATF call-for-action list (Iran, North Korea, Myanmar) | FATF public statements |
| Any mined source = ASM and jurisdiction risk score 3 | OECD Due Diligence Guidance, Annex II red flag |
3 · Otherwise the numeric band applies.
Risk data: baseline + overrides
The country/activity/material scores embedded in index.html are the firm-approved baseline (versioned as RISK_DATA_VERSION; changes to it go through a pull request, so git history remains the official audit trail and CI validates every change).
On top of the baseline, the Risk Data panel (sidebar → ⚙ Risk Data) lets the compliance function apply local overrides:
- Change any score (1–3 for countries/activities, 0–3 for materials) or a country's CFA (FATF call-for-action) flag - a reason is mandatory and the change is date-stamped.
- Overrides are stored as deltas in the browser (
localStorage) and as a portable risk data sheet (JSON export/import), so one approved sheet can be distributed to the whole team.
- Factors affected by an override are marked ✱ in the form, the score breakdown, and the printed report, which also lists each applied override ("Jurisdiction - Hungary: 2 → 3, overridden 12 Jun 2026 - FATF grey-listing") and carries a risk-data version stamp.
- Reset removes all overrides. When the firm formally adopts a change, it graduates into the baseline arrays via a PR and the override is retired.
Analyst override
Separately from the risk data (which is firm-wide), the analyst may raise the operative outcome of a single assessment above the computed one - CDD → SDD/EDD or SDD → EDD - with a mandatory justification. It is a one-way ratchet: it can never weaken the computed outcome, is inert without a justification, and never applies to PROHIBITED relationships. The suggested review cadence follows the overridden band, and the report records both the computed and the overridden outcome.
Data management & privacy
- Autosave - the working draft is saved to
localStorage in the user's browser only; nothing is transmitted anywhere.
- Print report - produces an audit-ready PDF via the browser's print dialog. Chrome/Edge/Firefox apply A4 and exact colours automatically; in Safari, choose A4 paper size and enable Print backgrounds in the print dialog.
Device security
For an offline, zero-backend tool, sensitive data is protected on the device rather than behind a server:
- Encryption at rest - assessments, the register, risk-data overrides, Asana payloads and the activity log are encrypted in
localStorage with AES-256-GCM (WebCrypto). The key is derived from the officer's passphrase via PBKDF2 (250k iterations, random salt); each write uses a fresh IV. On first run you can set a passphrase or continue unencrypted; the choice is remembered. There is no recovery - store the passphrase securely.
- Passphrase gate & idle auto-lock - the app prompts to unlock on each visit and re-locks after 15 minutes of inactivity (or via the Lock device button). The scoring engine still renders underneath the gate, so the page always computes.
- Tamper-evident activity log - a SHA-256 hash-chained record of completions, overrides, exports, deletions and unlocks. View it via ▤ Activity Log (with a chain-integrity check), export it, or read the last entries as an appendix in the printed report.
- Edge & function hardening - a strict Content-Security-Policy, HSTS and anti-clickjacking headers are applied to every response (
netlify.toml); the Asana relay functions enforce a same-origin / ALLOWED_ORIGINS allow-list.
A full mapping of this app against the AI Governance & Security Periodic Table (2026) - what applies, what is implemented, and what is out of scope for the deterministic, on-device RA engine, plus the tiles that apply to the optional LLM-backed Advisor (brain-soul.js) - is in docs/governance/ai-governance-gap-analysis-2026.md.
The complete governance pack - policy, framework mappings (ISO/IEC 42001, NIST AI RMF, EU AI Act, UAE AI Charter), risk/impact assessments, registers, and runbooks - is indexed in docs/governance/README.md; the ISO/IEC 42001 AIMS document pack (risk register, SoA, internal audit, management review, CAPA, decommissioning) in docs/aims/README.md; and the per-model cards in docs/models/README.md.
The suite is also mapped against the 6 Layers of Agentic AI Governance (AI visibility → AI assurance) in docs/governance/agentic-ai-governance-6layers-2026.md, supported by:
docs/governance/ai-asset-register.md (+ machine-readable data/ai-assets.json) - the AI inventory and risk tiering (Layer 1);docs/governance/data-retention.md - data stores, retention and lineage (Layer 2); enforced by purgeStaleDraft in index.html;docs/governance/dpia-2026.md - Data Protection Impact Assessment (Layer 2);docs/governance/advisor-bias-review-2026.md - paired-prompt bias-review method + log (Layer 2/4);docs/governance/nist-ai-rmf-mapping-2026.md and docs/governance/iso-42001-soa-2026.md - NIST AI RMF crosswalk + ISO 42001 Statement of Applicability (Layer 6);docs/governance/ai-incident-runbook.md and docs/governance/ai-acceptable-use-policy.md - incident response/kill switch + acceptable use (Layer 6);test/advisor-assurance.test.js + test/ai-assets.test.js + test/data-json.test.js (offline, in CI) and scripts/advisor-eval.mjs / scripts/advisor-bias-eval.mjs (key-gated, weekly/quarterly) - Advisor red-team, charter-drift, register-schema, JSON-integrity, plus live behavioural and bias assurance (Layer 1/2/4). Runtime guards in : PII flag, output-structure validator, budget flag, and an kill switch; in-app AUP acknowledgment gate in .
Setup
Asana integration
Copy .env.example to .env (never commit it) and fill in the values, then add them to your hosting environment:
| Variable | Required | Purpose |
|---|
ASANA_ACCESS_TOKEN | Yes | Personal access token from Asana Developer Console. Used by Netlify functions and the GitHub Actions watchdog. Add to GitHub Secrets and Netlify environment variables. |
ASANA_PROJECT_GID | Recommended | GID of the RISK ASSESSMENTS Asana project (from the project URL). Defaults to the built-in value - set explicitly to avoid targeting the wrong project after a project rename or workspace change. |
ASANA_ASSIGNEE | No | Asana user to assign tasks to. Defaults to me (the token bearer). |
ALLOWED_ORIGINS | No | Comma-separated extra browser origins permitted to call the Netlify functions. Same-origin requests and header-less (server-to-server) calls are always allowed; cross-site browser origins are rejected with 403. |
APP_SHARED_TOKEN | Recommended for real data | Shared-secret gate for the Netlify functions. The asana-mirror (register + activity-log) and risk-backup (risk-data sheet) relays carry customer data off-device and a read returns it, so when this is set they require an X-App-Token on every path - including the browser (the Origin header is forgeable). Leave blank and those relays are effectively public; a deployment that files real customer data should set this and fill the matching <meta name="hsra-app-token"> value in the three HTML pages (or rely on the on-device tokenise - no PII delivery option). See netlify/functions/_auth.js. |
APP_STRICT_TOKEN | No | Set to 1 to require X-App-Token on every request to every function (including the task-write endpoint and the browser path) - the only mode that resists Origin forgery. Requires APP_SHARED_TOKEN. |
Getting started
Open directly - download index.html and open it in any modern browser.
Serve locally:
python3 -m http.server 8000
# → http://localhost:8000
Self-host (container) - every release publishes a provenance-attested image to GHCR (publish-container.yml); versions track APP_VERSION:
docker run -p 8080:8080 ghcr.io/trex0092/hawkeye-sterling-ra:latest
# → http://localhost:8080
The image serves the same static tree as the live site - as a non-root process with the same security headers the Netlify edge sets (CSP, HSTS, COOP/COEP - see sws.toml) and a /health probe endpoint; the Netlify functions (Asana relay, AI brain, encrypted backup) are absent and the app degrades gracefully - all assessment data stays on-device either way.
Deploy - the Netlify project hawkeye-sterling-ra publishes the repo root as-is (netlify.toml, no build step). Link the repository to the project in the Netlify UI for continuous deploys, or deploy any other static host - the app is index.html plus its same-origin app.js (and the console.html/advisor.html pages with their *.js).
Tests
The scoring engine, hard-outcome escalations, persistence, and report rendering are covered by a dependency-free test suite that executes the app's full script (app.js) against a DOM stub:
node test/app.test.js # checks - engine, register, report, Asana delivery & backup, edge cases
node test/watchdog.test.mjs # 20 checks - FATF list parsing, alerts, digest, backup extraction
CI runs both suites plus two headless-Chrome smoke tests (one with prefers-reduced-motion for stability, one with motion enabled to exercise animation code paths) on every push and pull request (.github/workflows/ci.yml).
With the dev toolchain installed (npm ci - lockfile-pinned, no runtime dependencies), the same suites run as npm scripts: npm test (every test/*.test.js / test/*.test.mjs - exactly the set CI runs), npm run lint, npm run lint:html, and npm run test:visual / npm run test:e2e (after npx playwright install chromium). The unit suites themselves remain dependency-free - any single one still runs directly with node test/<file>.
Accessibility
The application targets WCAG 2.1 Level AA for its core assessment workflow:
- All interactive controls have visible labels and
aria-pressed state on Yes/No toggles.
- A persistent warning banner is shown if the browser's localStorage is blocked or full, directing the user to export their work.
- The gauge and risk-position bar are decorative; the score and verdict are also rendered as text.
- Animations respect the
prefers-reduced-motion media query - the gauge draw-in and count-up are skipped when motion is reduced.
Known limitations: colour-contrast of some badge colours has not been independently audited. The print report requires the user to enable "Print backgrounds" in Safari and Firefox print dialogs.
Project structure
.
├── index.html # Application markup (CSP: no inline script/style)
├── app.js # Application logic (scoring, data, persistence, UI wiring)
├── app.css # Application styles (externalised for a pure-'self' CSP)
├── console.js / advisor.js # Logic for the console + advisor pages
├── fonts.css / assets/fonts/ # Self-hosted web fonts (no third-party origin)
├── mcp_server.py # MCP stdio server (zero-dep JSON-RPC 2.0) exposing the engine
├── mcp_tools.py # Deterministic MCP tool wrappers over screen/kyc/txn_monitor
├── test/mcp_tools_test.py # MCP server + tool-layer unit tests
├── docs/mcp-server.md # MCP server reference (tools, resources, prompts, safety)
├── test/app.test.js # Functional test suite (no dependencies)
├── test/watchdog.test.mjs # FATF watchdog unit tests
├── test/reg-watch.test.mjs # Regulatory Watch unit tests
├── scripts/fatf-watchdog.mjs # Monthly FATF black/grey list watchdog (Asana alerts)
├── scripts/reg-watch.mjs # Weekly worldwide regulatory-source watcher (opens a PR)
├── scripts/reg-draft.mjs # Optional AI update proposal (needs ANTHROPIC_API_KEY)
├── scripts/sanctions-screen.mjs # Daily customer screening vs sanctions/watchlists (Asana alerts)
├── data/sanctions-screen-state.json # Last-seen matches (committed by the action; no re-alert spam)
├── data/fatf-state.json # Watchdog's last-seen FATF lists (committed by the action)
├── data/reg-sources.json # Regulatory Watch source registry + per-source narratives
├── data/reg-watch-state.json # Regulatory Watch content fingerprints (committed by the action)
├── docs/regulatory-watch.md # Regulatory Watch: source narratives + how it works
├── docs/cybersecurity-skills.md # Claude Code plugin: Anthropic Cybersecurity Skills (817 skills)
├── .claude/settings.json # Pre-registers the cybersecurity-skills plugin marketplace
├── .github/workflows/ # CI, FATF watchdog, Regulatory Watch, site health, releases
├── scripts/asana-alert.mjs # Asana alert task helper (used by site health)
├── package.json / package-lock.json # Dev/CI toolchain, lockfile-pinned (zero runtime npm deps)
├── pyproject.toml # Python engine metadata (runtime pins stay in ci/requirements.txt)
├── Dockerfile # Self-hosting image (GHCR, digest-pinned base, published per release)
├── netlify.toml # Static publish config (repo root, no build)
├── netlify/functions/ # Serverless: Asana task delivery + risk-data mirror
├── docs/ # ~190 documents - see docs/ for the full estate
│ ├── aims/ # ISO/IEC 42001 AIMS pack (risk register, BCP, audits…)
│ ├── governance/ # AI policy, crosswalks, registers, ADRs, readiness review
│ ├── policies/ # AML/CFT/CPF policy pack
│ ├── models/ # Per-feature model cards
│ ├── security/ # Runbooks (history scrub, deploy rollback), scanning triage
│ ├── architecture/ # System context, trust boundaries, data flows
│ ├── executive/ # Brief, ROI, readiness, roadmap, KPI dashboard
│ ├── user-guides/ # Analyst / administrator / reviewer-MLRO guides
│ ├── api/ # Netlify functions reference
│ ├── research/ # Regulatory research + auto-generated updates
│ ├── demo/ # Demo script, sample data, scenarios
│ └── screenshots/ # README captures of the three screens
├── design/ # Original design handoff (reference only, not served logic)
├── GOVERNANCE.md # Repository decision rights (Board / MLRO / maintainer)
├── MAINTAINERS.md # Maintainer roster + succession record
├── CLAUDE.md # Enforced invariants, for AI agents and second operators
└── README.md
System state & known limitations
An honest map of what runs, what waits on a human act, and where the accepted
architectural limits are. The tracking record is the
open-actions register; the horizon
view is the roadmap.
- Transaction monitoring is built and inert. The FATF R.16 rules engine
(
txn_monitor.py) is implemented and unit-tested but INACTIVE until a
transaction feed is connected (TXN_FEED_PATH) - register item 6, risk
R-13. An interim manual compensating control was adopted 2026-07-29.
- Part of the policy pack is draft. Two procedures are approved and in
force; sixteen instruments await Board approval (register item 18).
- Function endpoints can be effectively public when
APP_SHARED_TOKEN is unset.
Confidential read relays require X-App-Token when the shared token is configured,
but that shared bearer secret is still not verified per-user identity or RBAC. The
repository does not infer the live environment setting; verified identity is register
item 20. See netlify/functions/_auth.js.
- Assessments and the activity log are primarily on-device (
localStorage).
Asana mirrors provide off-device operational copies of the assessment register,
activity log and risk-data overrides, but there is no dedicated authenticated
persistence tier with a documented and rehearsed assessment-data RPO/RTO. That
remaining preservation gap is register item 23.
- LLM runtime state is mixed and must not be inferred from defaults. The Advisor
is an active on-request Anthropic surface. Adverse-media triage code defaults OFF
and requires explicit
LLM_TRIAGE=1, but the repository cannot read the live
repo-variable value; the third-party register preserves a 2026-07-16 owner
attestation that it was enabled while the formal DPA/go-live evidence remains
unresolved. Items 36 and 42 reconcile the legal and runtime records.
- Alert delivery is Asana-only. A delivery failure fails the run loudly,
but no second channel pages anyone - register item 21.
- Arabic coverage is partial. The assessment screen is fully translated;
console/advisor carry minimal AR chrome (register item 28), and long-form
legal prose stays English by recorded decision
(
docs/i18n-ar-legal-review.md).
- Accessibility limitations are listed under
Accessibility.
Contributing & support
Security
Found a vulnerability? Do not open a public issue - follow the disclosure process in SECURITY.md. Incident response and the Advisor kill switch are documented in docs/governance/ai-incident-runbook.md.
The architecture, trust boundaries, and a STRIDE threat model are in docs/architecture.md. Static analysis runs CodeQL plus Semgrep - generic community rulesets advisory, and app-specific security invariants (.semgrep/hawkeye.yml: no eval/new Function, no document.write, no child_process, no secret reads in client code) blocking in CI. Releases ship a CycloneDX SBOM and a Sigstore-keyless build-provenance attestation - verify a downloaded artifact with gh attestation verify <file> --repo trex0092/HAWKEYE-STERLING-RA.
Cybersecurity Skills (Claude Code plugin)
This repo pre-registers the Apache-2.0 Anthropic Cybersecurity Skills library (817 agent skills across 29 domains, mapped to MITRE ATT&CK / F3, NIST CSF / AI RMF, ATLAS and D3FEND) as a Claude Code plugin via .claude/settings.json. It gives Claude Code expert decision-workflows for the fraud-typology, threat-intelligence, and deployment-security work around this AML/CFT tool - see docs/cybersecurity-skills.md for what installs, how it maps to Hawkeye Sterling, and the authorized-use scope. The Advisor's own typologies are mapped to the MITRE F3 (Fight Fraud Framework) tactics in docs/fraud-f3-mapping.md.
License
Proprietary - All Rights Reserved. See LICENSE. The source is provided for authorized internal compliance use; redistribution, modification, or commercial use requires written permission.
Disclaimer
This tool is for internal compliance use only. It supports - and does not replace - professional judgement, firm policy, and applicable AML/CFT regulatory obligations. Country, activity, and material risk scores are template values sourced from the firm's risk data sheet and should be reviewed and maintained by the compliance function.
