canonical: https://jentic.com/apis/circl.lu/circl

# Circl Lu hashlookup CIRCL API

CIRCL hashlookup is a free, public threat-intelligence service from the Computer Incident Response Center Luxembourg that lets investigators check file hashes against a known-files database covering NSRL, manufacturer software releases, and other curated datasets. The API exposes 11 endpoints over https://hashlookup.circl.lu, supporting MD5, SHA-1, and SHA-256 lookups, bulk lookups for batches, and parent or child relationship traversal between related files. It is widely used in DFIR, malware triage, and software supply-chain checks to quickly separate known-good files from candidates that warrant deeper analysis. The service is open and licensed CC-BY, with optional session keys to retain context across queries.

## For AI agents

Look up file hashes (MD5, SHA-1, SHA-256) against the CIRCL hashlookup known-files database to identify known-good or known-bad files during DFIR and malware triage. Supports single and bulk lookups across 11 endpoints.

## Scope

Does not handle malware sandboxing, file submission, or live network IOC feeds - use for known-files hash lookup against the CIRCL dataset only.

## Capabilities

- Look up an MD5 hash to determine whether a file is in the known-files dataset
- Look up an SHA-1 or SHA-256 hash for forensic triage of recovered files
- Submit a JSON array of MD5 or SHA-1 hashes for bulk lookup in a single request
- Walk parent and child relationships between related files using paginated SHA-1 traversal
- Create a named session to retain hash-lookup context across multiple queries
- Retrieve current database statistics and the top 100 most-queried hashes
- Pull general info about the hashlookup database to confirm dataset coverage before triage

## Use cases

### DFIR Triage of a Forensic Image

During digital forensics and incident response, investigators commonly need to filter out known-good operating-system and application files so they can focus on suspicious binaries. CIRCL hashlookup accepts MD5, SHA-1, or SHA-256 lookups against datasets that include NSRL, allowing a triage script to run thousands of file hashes from an evidence image and quickly separate known files from unknowns. Bulk endpoints reduce round-trips and finish a typical workstation triage in minutes.

Example prompt: POST a JSON body with a hashes array of 500 MD5 values to /bulk/md5 and return the list that matched the CIRCL dataset.

### Malware Sample Pre-Check

Before submitting a suspected sample to a sandbox, an analyst can call /lookup/sha256/{sha256} to check whether CIRCL already recognises the hash as a known-good file from a manufacturer release. This shortcuts false positives on legitimate signed binaries - a common situation when EDR alerts on a hash that matches a known build artifact.

Example prompt: GET /lookup/sha256/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 and return whether the file is in the known-files dataset.

### Software Supply-Chain Verification

Build pipelines and software bill-of-materials tooling can use the parent and child traversal endpoints to verify that an artefact's hash maps to a known component family. /parents and /children take a SHA-1, count, and cursor, returning paginated relationship data so a CI job can confirm an installer or library belongs to an expected upstream package set.

Example prompt: GET /parents/{sha1}/100/0 for sha1=da39a3ee5e6b4b0d3255bfef95601890afd80709 and list the parent file hashes returned.

### AI Agent SOC Assist

An AI agent invoked through Jentic can take a list of file hashes flagged by an EDR alert, query CIRCL hashlookup, and return a summary of which are known-good versus unknown - without holding any credentials, since CIRCL hashlookup is unauthenticated. Jentic standardises the call shape so the agent does not need to learn the URL pattern for each hash type.

Example prompt: Search Jentic for 'lookup file hash in CIRCL hashlookup', load the GET /lookup/sha1/{sha1} schema, and call it for each SHA-1 from the alert payload.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /lookup/md5/{md5} | Look up a single MD5 hash |
| GET | /lookup/sha1/{sha1} | Look up a single SHA-1 hash |
| GET | /lookup/sha256/{sha256} | Look up a single SHA-256 hash |
| POST | /bulk/md5 | Bulk lookup an array of MD5 hashes |
| POST | /bulk/sha1 | Bulk lookup an array of SHA-1 hashes |
| GET | /parents/{sha1}/{count}/{cursor} | Paginated parents of a SHA-1 |
| GET | /info | Database info and dataset coverage |

## Key resources

- **Lookup** — Single-hash lookup endpoints for MD5, SHA-1, and SHA-256
- **Bulk** — Bulk lookup endpoints accepting a JSON hashes array
- **Relationships** — Parents and children endpoints for traversing related SHA-1 files
- **Sessions** — Create and retrieve named sessions to retain query context
- **Stats** — Database info and top-100 most-queried hashes

## Why Jentic

- **Setup:** Wiring the CIRCL hashlookup service by hand means calling its per-hash lookup and bulk endpoints and parsing the known-files dataset responses yourself, even though the service needs no credential. Through Jentic you install once, import the hashlookup CIRCL API from the API Directory, and your agent calls it.
- **Permission scoping:** hashlookup is a read-only service, so scope the agent to the lookup operations it needs, such as checking an MD5, SHA1, or SHA256 against the CIRCL dataset. You choose the operations it may call, so bulk lookups or parent-hash traversal are included only if you add them.
- **Credential handling:** hashlookup requires no credential, so there is nothing to store; if you later put it behind your own gateway key, Jentic One stores that key encrypted and injects it at execution time so it never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check if a file hash is known' or 'look up a SHA256 in the CIRCL dataset', and Jentic returns the matching hashlookup operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Cisco API** — Cisco security telemetry combines well with CIRCL hashlookup for endpoint hash enrichment.
- **Circle API** — Circle hosts security communities that consume CIRCL threat-intel data.
- **CINNOX API** — CINNOX delivers security alert messaging while CIRCL hashlookup enriches the underlying IOCs.

## FAQ

### What authentication does the CIRCL hashlookup API use?

CIRCL hashlookup is a free public service and does not require authentication - there is no API key. Through Jentic, you can call it without configuring any credential and Jentic will execute the request directly against https://hashlookup.circl.lu.

### Can I look up SHA-256 hashes with the CIRCL hashlookup API?

Yes. GET /lookup/sha256/{sha256} returns dataset metadata for a single SHA-256 hash. The API also supports MD5 via /lookup/md5/{md5} and SHA-1 via /lookup/sha1/{sha1}, with bulk equivalents for MD5 and SHA-1.

### What are the rate limits for CIRCL hashlookup?

CIRCL does not publish hard rate limits in the OpenAPI spec, but the service is community-funded, so respect fair-use guidance on the project page and prefer the bulk endpoints for batches. Jentic surfaces 429 responses transparently if throttling is applied.

### How do I bulk-check a list of MD5 hashes through Jentic?

Run pip install jentic, then search Jentic for 'bulk hash lookup CIRCL'. Jentic returns the POST /bulk/md5 operation. Load the schema, supply a JSON body with a 'hashes' array of MD5 strings, and execute. Get started with Jentic One, the self-hosted execution layer.

### What datasets does CIRCL hashlookup cover?

The dataset includes NSRL (NIST National Software Reference Library), manufacturer software releases, and other curated known-files sources. Call GET /info to retrieve current dataset metadata and coverage. Combined with /stats/top this lets you confirm freshness before relying on results for triage.

### Can I traverse relationships between known files?

Yes. GET /parents/{sha1}/{count}/{cursor} and GET /children/{sha1}/{count}/{cursor} return paginated parent and child SHA-1 hashes for a given file, useful for mapping installer to component relationships in supply-chain verification.

### Can I limit what my agent is allowed to do with the CIRCL hashlookup API?

Yes. Because Jentic One is self-hosted, you decide which hashlookup operations your agent may call, and your own rules enforce that scope. hashlookup is read-only, so you can restrict the agent to just the single-hash lookups it needs, such as GET /lookup/md5/{md5}, /lookup/sha1/{sha1}, or /lookup/sha256/{sha256}, and add the bulk endpoints or parent and child SHA-1 traversal only when you want them available. Any operation you do not grant is simply not callable by the agent.