HashScanner Python Client
Python client for the HashScanner API — query 1.5 billion+ NIST NSRL known file hashes (MD5 / SHA-1 / SHA-256) by API, single or in bulk.
HashScanner puts the NIST National Software Reference Library online so you can filter the known out of your data and focus on the unknown — without downloading and maintaining the ~700 GB RDS yourself.
🔑 You need a free API key. Create an account at https://www.hashscanner.com/register — every plan (including the free tier) includes API access. Your key is in your dashboard.
Install
pip install hashscanner
Quick start
from hashscanner import Client
hs = Client("hs_xxxx_sk_xxxx") # or set HASHSCANNER_API_KEY
result = hs.lookup("d41d8cd98f00b204e9800998ecf8427e")
if result.found:
print(result.type, result.file_name, result.product, "via", result.source)
else:
print("not in NSRL — worth a closer look")
A match means the file is known (cataloged in NSRL) — not that it is safe, clean, or malicious. Use it to set aside files you already recognise.
Bulk lookups (async)
For large sets — up to 100,000 hashes per job — submit a bulk job. The client handles the submit → poll → download flow for you:
hashes = ["d41d8cd9...", "da39a3ee...", ...]
# JSON: returns a list of result dicts
for record in hs.bulk(hashes):
print(record["hash"], record["found"])
# CSV: returns the raw CSV text
csv_text = hs.bulk(hashes, format="csv")
Prefer to drive the steps yourself?
job = hs.submit_bulk(hashes, format="json") # -> BulkJob (queued)
job = hs.wait(job, poll_interval=3) # poll until completed/failed
for record in hs.iter_results(job): # stream NDJSON results
...
A few small lookups concurrently
results = hs.lookup_many(["<hash1>", "<hash2>", "<hash3>"])
Command line
The package installs a hashscanner command:
export HASHSCANNER_API_KEY="hs_xxxx_sk_xxxx"
# single lookup
hashscanner lookup d41d8cd98f00b204e9800998ecf8427e
hashscanner lookup d41d8cd9... --json
# bulk: one hash per line (use '-' for stdin), JSON (NDJSON) or CSV
hashscanner bulk hashes.txt
hashscanner bulk hashes.txt --format csv -o results.csv
cat hashes.txt | hashscanner bulk -
Errors
All errors derive from hashscanner.HashScannerError:
| Exception | When |
|---|---|
AuthenticationError |
401 — key missing/invalid |
SubscriptionInactiveError |
403 — renew/upgrade |
RateLimitError |
429 — per-minute rate limit or monthly quota (.retry_after, .reset) |
BadRequestError |
400 — bad hash / job too large |
NotFoundError |
404 — unknown/expired bulk job |
JobFailedError |
bulk job finished failed |
APIError |
other non-2xx |
A single-lookup miss is not an error — it returns LookupResult(found=False).
Links
- API documentation: https://www.hashscanner.com/api
- Pricing & limits: https://www.hashscanner.com/pricing
- Sign up (free): https://www.hashscanner.com/register
License
MIT
Metadata
Release files for hashscanner 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hashscanner-0.1.0.tar.gz | 10.9 kB | Without provenance | Details for hashscanner-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hashscanner-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for hashscanner-0.1.0-py3-none-any.whl |
Total release size: 22.8 kB
Release files / hashscanner-0.1.0.tar.gz
| Download URL | hashscanner-0.1.0.tar.gz |
|---|---|
| Size | 10.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
eee766a74cdfd6f86e95671d62dc25d15b594984d0074fc0b354ff2bdfd2c789
|
|
BLAKE2b-256 checksum How to use checksums |
330dff8746470c76396ff93f118908c2c3f41553170569622ebe6d624f4b46fa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / hashscanner-0.1.0-py3-none-any.whl
| Download URL | hashscanner-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
27044b9690ed25ca1f153df3befa0a188269d33eccca0bd1c439858bb3ff8e08
|
|
BLAKE2b-256 checksum How to use checksums |
f48942110338a0946bb59585601d184f3a74c19a094e69f05fbc19c655afa7d1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for hashscanner 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.