nano SIEM
Enrichments

Custom enrichments

Supported in:Self-hosted

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

KindWhat it doesExample
Enrich at ingest (data)Runs on a schedule and returns a set of records that new events are matched againstIP blocklist, asset list
Agent lookupCalled on demand during an AI investigation or triage for a single valueVirusTotal, 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

KindWhat new events get
Context (Threat Intel / IOC off), IP keysThe 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 / IOCIndicators 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.ip

The 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.subtle digest and HMAC, atob/btoa, JSON, Date, setTimeout and console. There is no Deno or Node API, no file system, no environment and no import.
  • 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.X is 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.
LimitValue
Code size1 MiB
Allowed domains10 per enrichment
Timeout, scheduled run600 s by default, up to 1,800 s
Timeout, agent lookup120 s (operators can set ENRICHMENT_AGENT_LOOKUP_TIMEOUT_SECS, up to 600 s)
Memory1 GiB for a scheduled run, 128 MiB for an agent lookup
File system, environment and shellNone

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.

ReasonFix
A plain http:// URL, or an allowed domain with http:// or a port other than 443Use 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 variableSend 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 doUse a declarative connector instead
The code doesn't compileFix 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.

What's next

On this page