Custom enrichments
Bring your own feed: TypeScript that runs in a sandbox on a schedule and enriches matching events at ingest. Included with nano Self-run.
Create a custom enrichment to add context from your own IP blocklist, asset list, or threat-intelligence API. You write TypeScript that fetches the feed on a schedule; nano compiles it to WebAssembly when you save it, runs it in an embedded sandbox, stores its records in ClickHouse, and serves them from a dictionary at ingest.
Two kinds
| Kind | What it does | Example |
|---|---|---|
| Enrich at ingest (data) | Runs on a schedule and returns a set of records that new events are matched against | IP blocklist, asset list |
| Agent lookup | Called on demand during an AI investigation or triage for a single value | VirusTotal, AbuseIPDB, Shodan |
Create an enrichment
The wizard is at Marketplace → Create Custom.
Choose the kind
Pick Enrich at Ingest or Agent Lookup. For threat-intel data (blocklists, malware hashes), turn on Threat Intel / IOC: the records become indicators for ioc searches and retro hunts instead of context tags.
Name it and pick the key type
Choose a name you'll recognize in run history and ioc results. The key type (IP, domain, hash, URL, …) decides which event fields are matched.
Set the schedule and allowed domains
Set a cron schedule (default 0 */6 * * *, every 6 hours). List every domain the code fetches from, exactly as written in the URL (for example lists.blocklist.de). The sandbox blocks every other host, and the domains are checked so you can't allow loopback, private or cloud-metadata addresses.
Write or generate the code
Write the TypeScript yourself, or let pivt generate it from a description, a working curl command and a sample response. Review generated code before going on.
Validate, deploy and install
Run Validation executes the code against the real source and checks the records it returns. Then Deploy and Install, open the enrichment and choose Sync Now for the first run.
Code contract
The program exports an enrich function that returns records:
interface EnrichmentRecord {
key: string; // the value to match: IP, domain, hash, URL…
risk_score?: number; // 0–100
tags?: string[];
data?: object; // any extra fields, kept on the match
// IOC enrichments: set these at the top level, not inside data
threat_type?: string; // e.g. "botnet_cc", "phishing", "scanner"
confidence?: number; // 0–100
malware?: string; // malware family, or ""
}
interface EnrichmentOutput {
records: EnrichmentRecord[];
watermark?: string; // passed back on the next run, for incremental feeds
}
export async function enrich(): Promise<EnrichmentOutput> {
const res = await fetch("https://lists.blocklist.de/lists/all.txt");
const records = (await res.text())
.split("\n")
.map((line) => line.trim())
.filter((ip) => ip.length > 0)
.map((ip) => ({ key: ip, risk_score: 70, tags: ["blocklist_de"], threat_type: "scanner", confidence: 70, malware: "" }));
return { records };
}What a match writes
| Kind | What new events get |
|---|---|
| Context (Threat Intel / IOC off), IP keys | The record's tags, comma-separated, in enrichments.custom_src_ip_tags or enrichments.custom_dest_ip_tags when src_endpoint.ip or dst_endpoint.ip matches |
| Threat Intel / IOC | Indicators are matched by ioc searches and retro hunts. They aren't stamped onto events at ingest |
Only new events are enriched. To check older events against a feed, use lookup or a retro hunt.
enrichments.custom_src_ip_tags=* | stats count by enrichments.custom_src_ip_tags, src_endpoint.ipThe sandbox
Since nano 2.0.15, custom enrichment code runs in an embedded WebAssembly sandbox; the earlier Deno runtime is gone. The code compiles when you save it, and the editor shows any error at its line.
- Web APIs only.
fetch,Request/Response/Headers,URL,TextEncoder/TextDecoder, streams,crypto.subtledigest and HMAC,atob/btoa,JSON,Date,setTimeoutandconsole. There is no Deno or Node API, no file system, no environment and noimport. - Network. Only https on port 443, and only to the enrichment's allowed domains. Plain
http://is refused. Every request goes through nano's egress gate, which also refuses private, loopback and link-local addresses and doesn't follow redirects. - Credentials.
credentials.Xis an opaque placeholder. nano puts the real secret only into request headers sent to an allowed domain, so your code never holds it. When you pick an auth type (basic, bearer, OAuth2, service account), nano adds the header for you.
| Limit | Value |
|---|---|
| Code size | 1 MiB |
| Allowed domains | 10 per enrichment |
| Timeout, scheduled run | 600 s by default, up to 1,800 s |
| Timeout, agent lookup | 120 s (operators can set ENRICHMENT_AGENT_LOOKUP_TIMEOUT_SECS, up to 600 s) |
| Memory | 1 GiB for a scheduled run, 128 MiB for an agent lookup |
| File system, environment and shell | None |
Needs attention
nano checks every enrichment when it's saved and after an upgrade. The Marketplace badge reads wasm ready when the code runs on the sandbox, or needs attention · not running when it can't. An enrichment that needs attention doesn't run: each run is refused with the reason, and the vendor isn't called. Other enrichments keep running. Settings → SIEM health lists every enrichment in this state.
| Reason | Fix |
|---|---|
A plain http:// URL, or an allowed domain with http:// or a port other than 443 | Use the vendor's https endpoint on port 443 |
| A credential in a URL, query string or request body, including a copy of it in a variable | Send it as-is in a request header, for example headers: { "X-API-Key": credentials.API_KEY } |
A credential encoded, hashed or signed in code (btoa, crypto.subtle) | Pick an auth type so nano adds the header |
| The vendor needs something the sandbox can't do | Use a declarative connector instead |
| The code doesn't compile | Fix the error the editor shows at its line |
Save the fix; nano checks the enrichment again within a minute.
Run history
Each enrichment keeps a run history with status, record counts, timestamps and errors. Open it from Marketplace to see the last run, use Manual Run to test a change, and check the history when matches stop appearing.
Marketplace packages
The Marketplace also lists ready-made packages from the nano enrichment catalog. You supply the API key where the source needs one. Agent lookups include AbuseIPDB, GreyNoise, MalwareBazaar, AlienVault OTX, Shodan, URLhaus and VirusTotal.
ThreatFox and Tor exit nodes don't need a package: they arrive in the signed platform feed bundle.
Troubleshoot
Need help with these checks? Contact support with the request ID and time with timezone.
Validation or a scheduled run fails
Open the enrichment's run history in Marketplace. Check the allowed domains for network errors and the top-level IOC fields for format errors. See Custom enrichment troubleshooting for timeout and key-normalization checks.