components: parameters: ApiKeyPath: description: | Your abuse.ch API key, supplied as a URL path segment. Use these endpoints when your tooling can only be configured with a URL and cannot set HTTP headers. Treat this value with the same care as a password: it appears in the URL, so it will be recorded in proxy and browser logs. in: path name: api_key required: true schema: example: sk_prod1_WK5PZRP3ND.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx type: string Host: description: The host (IPv4 address, hostname or domain name) you want to query (case insensitive). examples: domain: summary: Fetch record by domain name. value: raw.githubusercontent.com ipv4: summary: Fetch record by MD5 hash. value: 182.122.199.91 in: path name: host required: true schema: type: string PayloadHash: description: The target payload hash, either `md5` or `sha256`. examples: md5: summary: Fetch record by MD5 hash. value: 59ce0baba11893f90527fc951ac69912 sha256: summary: Fetch record by SHA256 hash. value: 4293c1d8574dc87c58360d6bac3daa182f64f7785c9d41da5e0741d2b1817fc7 in: path name: hash required: true schema: pattern: ^[a-fA-F\d]{32}(?:[a-fA-F\d]{32})?$ type: string QueryPaginationAfter: description: "The cursor for retrieving the next page of results, as provided in the `next_page` field of the previous page's \nresponse.\n" in: query name: after required: false schema: type: string QueryPaginationPageSize: description: Number of items per page. in: query name: page_size required: false schema: example: 100 format: int64 maximum: 100 minimum: 1 type: integer QuerySince: description: The date and time from which to search for rules (RFC3339). in: query name: since required: false schema: example: "2024-01-10T19:17:22Z" format: date-time type: string QueryUntil: description: The date and time up to which to search, inclusive (RFC3339). Can be combined with 'since' to form a timeframe range. in: query name: until required: false schema: example: "2024-01-20T19:17:22Z" format: date-time type: string TargetUrl: description: The unique ID of the URL, or the double-URL-encoded URL. examples: encoded-url: summary: A lookup by URL-encoded URL (the URL must be URL-encoded twice). value: http%253A%252F%252F115.59.33.79%253A35371%252Fbin.sh id: summary: A lookup by unique identifier. value: "3597589" in: path name: target_url required: true schema: type: string responses: BadRequest: content: application/json: example: message: The client sent an invalid request. status: 400 schema: $ref: '#/components/schemas/Error' description: The client sent an invalid request. headers: Content-Type: description: The content type schema: enum: - application/json type: string Forbidden: content: application/json: example: message: The client lacks sufficient permissions to access the requested resource. status: 403 schema: $ref: '#/components/schemas/Error' description: The client is not authorized to access the requested resource. headers: Content-Type: description: The content type schema: enum: - application/json type: string InternalServerError: content: application/json: example: message: The server encountered an internal error. status: 500 schema: $ref: '#/components/schemas/Error' description: The server encountered an internal error. headers: Content-Type: description: The content type schema: enum: - application/json type: string NotFound: content: application/json: example: message: The requested resource was not found. status: 404 schema: $ref: '#/components/schemas/Error' description: The requested resource was not found. headers: Content-Type: description: The content type schema: enum: - application/json type: string Unauthorized: content: application/json: example: message: The client is not authorized to access the requested resource. status: 401 schema: $ref: '#/components/schemas/Error' description: The client is not authorized to access the requested resource. headers: Content-Type: description: The content type schema: enum: - application/json type: string schemas: AuthSession: description: "Log into the abuse.ch to obtain a session JWT (JSON Web Token). The returned JWT is valid for 24 hours from the time \nof issue.\n" properties: code: description: The HTTP status code of the response. example: 200 format: int64 type: integer expires: description: the Unix timestamp of when the token will expire, i.e. in 24 hours time. example: 1737026291 format: int64 type: integer token: description: The JWT to be used as the Bearer token for authenticating abuse.ch API requests. example: eyJ0eXAiOiJ1KV1QiL7CJhbGciOiJIUz3iJ9.eyJpYXQiOjE3MzY5Mzk4OTEsImV4cCI6MTczNzAyNjI5MSwiaXNzIjoic2hhcGktYXV0aCIsIm2F1ZCI6ImludGVsIiwic3ViIjoiMTM1MjI2MTciLc3IiOiJqZW1AZGV2LnNwYW1oYXVzIiwidGllciIh6eyJsdmwiOiJleHQiLCJhZHMiOiJmYQkwsQkNMLENTUyxET01BSU4sQS5VSCIsImFkdyI6MSwicW1zIjoxMDAwMDAwLCJxbWgiOjgwMDAwMDAsInJsX3FwaCI6NDAwMDAwMCwicmxfcXBtIjoxMDAwMDAsInJsX3FwcyI6MTAwMDB9fQ.40eAKZvl1Bu3vYU94FgHaeFzzLyzHysw4vV-o3RgKYs type: string required: - code - token - expires type: object Error: description: The server returned a HTTP error. properties: message: description: A human-readable message describing the error. type: string status: description: The HTTP status code. format: int64 type: integer required: - status - message type: object FileMetadata: description: The metadata for a file. properties: dhash_icon: description: The [dhash](https://github.com/benhoyt/dhash) of the sample's icon, if the file is a Portable Executable (PE) file. example: 00928e8e8686b800 type: string file_size: description: The size of the file in bytes. example: 143360 format: int64 type: integer file_type_mime: description: The MIME type of the file. example: application/x-dosexec type: string first_seen: description: The timestamp when the file was first seen (RFC3339). example: "2022-01-11T19:17:22Z" format: date-time type: string gimphash: description: The file's `imphash` equivalent for Go binaries, if available. example: a081e2fab5999d99ed6be718af55e93df171d14bc83c7ca5fdc0907edba0d338c type: string imphash: description: The file's import hash - only available for Portable Executable (PE) files. example: 98f67c550a7da65513e63ffd998f6b2e type: string md5_hash: description: The MD5 hash of the file. example: 4e22717b48f2f75fcfd47531c780b218 type: string sha1_hash: description: The SHA1 hash of the file. example: 60b637e95b1f2d14faaa71085b7e26321bfeeb6d type: string sha3_384_hash: description: The SHA3-384 hash of the file. example: 47c1b3eba75573642582d47a4c2259bc0f76fd1ab6bc81ca364d361f1f6bbc8263d961d5a42ce68f7af91c3366727a4d type: string sha256_hash: description: The SHA256 hash of the file. example: 7f94107c9becbcc6ca42070fca7e1e63f29cdd85cbbd8953bbca32a1b4f91219 type: string sightings: description: The number of sightings of the file. example: 28453 format: int64 type: integer ssdeep: description: The file's [ssdeep](https://ssdeep-project.github.io/ssdeep/index.html) fuzzy hash, if available. example: 3072:i4vzLk2RZ205s4wKj6iZqmCMXjkIIXXRxGj5YBcjmP0OE:TM2RsodwxRm5zVIfGFYPPRE type: string telfhash: description: The file's [Trend Micro ELF Hash](https://github.com/trendmicro/telfhash), if available. example: t1dd211d716b2195266ea0cd9088eca7b2512c97072349df33cf31849c24140aeea3ac4f type: string tlsh: description: The file's [Trend Micro Locality Sensitive Hash (TLSH)](https://github.com/trendmicro/tlsh), if available. example: T105E34B01F39381F7DC960CF2297AB62FDF7D1E032064DE9593945F1BAC72609A2A991C type: string required: - md5_hash - sha1_hash - sha256_hash - sha3_384_hash type: object FileMetadataList: description: The paginated list of file metadata search results. properties: items: description: The list of file metadata search results. items: $ref: '#/components/schemas/FileMetadata' type: array meta: $ref: '#/components/schemas/Pagination' required: - items - meta type: object HostDetails: description: URLhaus host entry with associated URLs. properties: blacklists: $ref: '#/components/schemas/UrlBlacklists' first_seen: description: The timestamp when the malware URL has been added to URLhaus (RFC3339). example: "2025-03-18T16:06:18Z" format: date-time type: string host: description: The unique identifier of the URLhaus entry. example: vektorex.com type: string last_seen: description: The timestamp when the malware URL has been spotted last time (RFC3339). example: "2025-03-18T16:06:18Z" format: date-time type: string url_count: description: The number of URLs observed on this host. example: 124 format: int64 type: integer urlhaus_reference: description: Link to URLhaus entry. example: https://urlhaus.abuse.ch/url/3481371/ format: uri type: string urls: description: List of URLs associated with this host. example: - https://raw.githubusercontent.com/d1ovu/pon/blob/main/res.bat items: format: uri type: string type: array required: - urlhaus_reference - host - first_seen - url_count - blacklists type: object HostsList: description: The paginated list of hosts. properties: items: description: The list of hosts. items: $ref: '#/components/schemas/HostDetails' type: array meta: $ref: '#/components/schemas/Pagination' required: - items - meta type: object Ioc: description: Indicator of Compromise (IOC). properties: comment: description: An optional comment from the reporter. example: These domains are too bad! type: string confidence_level: description: Indicates how sure the reporter is about this IOC. example: 50 format: int64 type: integer credits: description: A list of credits associated with the IOC. items: $ref: '#/components/schemas/IocCredits' type: array first_seen: description: The timestamp for when ThreatFox first saw this file (RFC3339). format: date-time type: string id: description: The unique identifier of the IOC. example: 41 format: int64 type: integer ioc: description: The actual indicator of compromise. example: gaga.com type: string ioc_type: description: The type of the IOC. example: domain type: string ioc_type_desc: description: The description of the corresponding IOC type. example: Domain that is used for botnet Command&control (C&C) type: string is_compromised: description: A submitter-provided indicator of whether the shared IOC is a compromised resource. example: false type: boolean last_seen: description: The timestamp for when ThreatFox last saw this file (RFC3339). format: date-time type: string malware: description: The associated malware family. example: win.ave_maria type: string malware_alias: description: An alias for the associated malware family. example: AVE_MARIA,AveMariaRAT,Warzone RAT,avemaria type: string malware_malpedia: description: The HTTP link to the corresponding Malpedia entry. example: https://malpedia.caad.fkie.fraunhofer.de/details/win.ave_maria format: uri type: string malware_printable: description: The human-readable name of the associated malware family. example: Ave Maria type: string malware_samples: description: A list of malware samples associated with the IOC. items: $ref: '#/components/schemas/IocMalwareSample' type: array reference: description: An optional HTTP link to a reference that contains more information about the IOC. example: https://twitter.com/JAMESWT_MHT/status/1336229725082177536 format: uri type: string reporter: description: The Twitter handle of the reporter (or `anonymous`). example: abuse_ch type: string sightings: description: The number of sightings of the IOC. example: 3 format: int64 type: integer tags: description: A list of tags associated with the IOC. example: - exe - test items: type: string type: array threat_type: description: The threat type of the IOC. Use the threat types API endpoint to determine possible values. example: botnet_cc type: string threat_type_desc: description: The description of the corresponding threat type. example: Indicator that identifies a botnet command&control server (C&C) type: string required: - confidence_level - credits - first_seen - id - ioc - ioc_type - ioc_type_desc - malware - malware_malpedia - malware_printable - reporter - sightings - tags - threat_type - threat_type_desc type: object IocCredits: description: Credits awarded to the user for submitting an IOC. properties: credits_amount: description: The number of credits awarded. example: 100 format: int64 type: integer credits_from: description: The platform that awarded the credits. example: ThreatFox type: string required: - credits_from - credits_amount type: object IocList: description: The paginated list of IOCs. properties: items: description: The list of IOCs. items: $ref: '#/components/schemas/Ioc' type: array meta: $ref: '#/components/schemas/Pagination' required: - items - meta type: object IocMalwareSample: description: Indicator of Compromise malware sample. properties: malware_bazaar_url: description: The URL to the sample on MalwareBazaar. example: https://bazaar.abuse.ch/sample/b325c92fa540edeb89b95dbfd4400c1cb33599c66859a87aead820e568a2ebe7/ format: uri type: string md5_hash: description: The MD5 hash of the sample. example: 5b7e82e051ade4b14d163eea2a17bf8b type: string sha256_hash: description: The SHA256 hash of the sample. example: b325c92fa540edeb89b95dbfd4400c1cb33599c66859a87aead820e568a2ebe7 type: string timestamp: description: The timestamp when the sample was seen (RFC3339). example: "2022-01-10T19:17:22Z" format: date-time type: string required: - timestamp - malware_bazaar_url type: object IocRevocation: description: | An IOC that ThreatFox no longer serves. A revocation asserts only that the entry has been withdrawn from the dataset — it is not a statement that the indicator was benign, nor that it is now safe. properties: id: description: The unique identifier of the ThreatFox IOC that was revoked. example: 1869889 format: int64 type: integer reason: description: | Why the entry was withdrawn, as far as it is known. - `absent_upstream`: the entry is no longer present in the community dataset. This covers expiry and false-positive removal, which are not distinguished upstream. - `removed_by_admin`: withdrawn by an abuse.ch administrator. - `removed_by_user`: withdrawn by the submitting user. - `unspecified`: no reason was recorded. enum: - absent_upstream - removed_by_admin - removed_by_user - unspecified example: absent_upstream type: string revoked_at: description: | When the entry was withdrawn, in RFC 3339 format. Ordering is by this value, then by `id` to break ties. Ties are common rather than exceptional: a bulk withdrawal stamps every entry it touches with a single timestamp. example: "2026-08-07T12:34:56Z" format: date-time type: string threatfox_reference: description: Link to the ThreatFox entry. example: https://threatfox.abuse.ch/ioc/1869889/ format: uri type: string required: - id - revoked_at - reason type: object IocRevocationList: description: | The paginated list of revoked IOCs, newest first. Shares its shape with the other abuse.ch revocation endpoints: the same envelope, the same `revoked_at` semantics and ordering, and the same pagination contract. The item identifier is each platform's own, because consumers withdraw records using the key they ingested them under. A revocation is not reversible information: if a withdrawal turns out to have been wrong and the record is reinstated, it stops appearing here without any event saying so. Treat this feed as a reason to re-check a record rather than as a permanent verdict on it. properties: items: description: The list of revoked IOCs. items: $ref: '#/components/schemas/IocRevocation' type: array meta: $ref: '#/components/schemas/Pagination' required: - items - meta type: object MalwareFamily: description: A Malware Family record. properties: malware_alias: description: An alias for the associated malware family. example: AVE_MARIA,AveMariaRAT,Warzone RAT,avemaria type: string malware_family: description: The malware family signature. example: win.ave_maria type: string malware_printable: description: The human-readable name of the associated malware family. example: Ave Maria type: string required: - malware_family type: object MalwareFamilyDetails: description: Malware family summary details - this is only available if the `malware_family` query was provided. properties: first_seen: description: The timestamp of when the malware family was first seen (RFC3339). format: date-time type: string last_seen: description: The timestamp of when the malware family was last seen (RFC3339). format: date-time type: string payload_count: description: The total number of observed payloads associated with this malware family. example: 12787 format: int64 type: integer url_count: description: The total number of observed URLs associated with this malware family. example: 2125 format: int64 type: integer required: - first_seen - last_seen - payload_count - url_count type: object MalwareFamilyList: description: The paginated list of Malware Family search results. properties: items: description: The list of Malware Family records. example: - malware_family: win.sparksrv malware_printable: Sparksrv - malware_family: win.sslmm malware_printable: SslMM - malware_alias: AVE_MARIA,AveMariaRAT,Warzone RAT,avemaria malware_family: win.ave_maria malware_printable: Ave Maria items: $ref: '#/components/schemas/MalwareFamily' type: array meta: $ref: '#/components/schemas/Pagination' required: - items - meta type: object MalwareSample: description: Details about a malware sample. properties: anonymous: description: Whether the submission was from an anonymous reporter. example: false type: boolean archive_pw: description: The password to decrypt the archive in case the file is a password-protected archive. example: password type: string comment: description: The comment provided by the submitter, if one was provided. example: | Malspam distributing AZORult: HELO: host.noanfair.com Sending IP: 69.64.34.145 From: akwenigroup@mweb.co.za Subject: New Order PO/A129901/20 From Akweni Group Attachment: New Order POA12990120 From Akweni Group.gz (contains "New Order POA12990120 From Akweni Group.exe") AZORult C2: http://185.239.242.174/owa/index.php type: string comments: description: A list of user comments associated with the malware sample. items: $ref: '#/components/schemas/MalwareSampleComment' type: array delivery_method: description: | The delivery method used to spread this malware sample. - `email_attachment`: Distributed via e-mail attachment. - `email_link`: Distributed via e-mail link. - `web_download`: Distributed via web download. - `web_drive-by`: Distributed via drive-by. - `multiple`: Multiple delivery methods used. - `other`: Other delivery methods used. enum: - email_attachment - email_link - web_download - web_drive-by - multiple - other example: email_attachment type: string dhash_icon: description: The [dhash](https://github.com/benhoyt/dhash) of the sample's icon, if the file is a Portable Executable (PE) file. example: f8dcbeffbffecee8 type: string file_information: description: A list of contextual information about the file sample. example: - context: dropped_by_md5 value: 6e11af9a2132859a07b369d52ce5ca69 - context: cape value: https://www.capesandbox.com/analysis/72842/ - context: dropped_by_sha256 value: 920f5880797ad30726cd5c3707fbba03f2e3e54de39a306a8903ce08b5301bdc items: $ref: '#/components/schemas/MalwareSampleFileInformation' type: array file_name: description: The malware sample's file name. example: New Order POA12990120 From Akweni Group.exe type: string file_size: description: The size of the malware sample in bytes. example: 903680 format: int64 type: integer file_type: description: The type of the malware sample. example: exe type: string file_type_mime: description: The MIME type of the malware sample. example: application/x-dosexec type: string first_seen: description: The timestamp for when MalwareBazaar first saw this file (RFC3339). example: "2020-10-19T09:54:37Z" format: date-time type: string gimphash: description: The file's `imphash` equivalent for Go binaries, if available. example: a081e2fab5999d99ed6be718af55e93df171d14bc83c7ca5fdc0907edba0d338c type: string humanhash: description: The file's [HumanHash](https://github.com/zacharyvoase/humanhash) - a human-readable representation of digests. example: oranges-hotel-bulldog-oranges type: string imphash: description: The file's import hash - only available for Portable Executable (PE) files. example: f34d5f2d4577ed6d9ceec516c1f5a744 type: string intelligence: $ref: '#/components/schemas/MalwareSampleIntelligence' magika: description: The result of the [Magika](https://github.com/google/magika) AI-powered file type identification. example: pebin type: string md5_hash: description: The MD5 hash of the malware sample. example: c40aead7a31d14e05b2ee4a11849eced type: string ole_information: $ref: '#/components/schemas/MalwareSampleOleInformation' origin_country: description: Two letter country code of the country where the sample was uploaded from. example: US type: string reporter: description: The Twitter handle of the reporter (or `anonymous`). example: viql type: string sha1_hash: description: The SHA1 hash of the malware sample. example: 77543bde72105ae1a28cc71815d9ea89ea162052 type: string sha3_384_hash: description: The SHA3-384 hash of the malware sample. example: 139b8890e573e4c759e4904902b3ece1b4b8c1fd7a49fc8ccd482226581c88e4d1ce074f0ab274238a87b273d8dc74e4 type: string sha256_hash: description: The SHA256 hash of the malware sample. example: 7de2c1bf58bce09eecc70476747d88a26163c3d6bb1d85235c24a558d1f16754 type: string signature: description: The malware family signature, if available. example: Adwind type: string ssdeep: description: The file's [ssdeep](https://ssdeep-project.github.io/ssdeep/index.html) fuzzy hash, if available. example: 12288:XxaJCK7NVuJfemYEV54zO26bb9A1GKZHNYPzodGCrJ:JJ4+4zkA1GUKzodGCr type: string tags: description: The list of associated tags. example: - AZORult - exe items: type: string type: array telfhash: description: The file's [Trend Micro ELF Hash](https://github.com/trendmicro/telfhash), if available. example: t1dd211d716b2195266ea0cd9088eca7b2512c97072349df33cf31849c24140aeea3ac4f type: string tlsh: description: The file's [Trend Micro Locality Sensitive Hash (TLSH)](https://github.com/trendmicro/tlsh), if available. example: AA15491232F50F49F8BE97F9562810918777BA9E513ED24C7D8D30DE4BA2B010A67B27 type: string trid: description: The [TrID](https://mark0.net/soft-trid-e.html) identifier of the file. example: - 52.2% (.DOCX) Word Microsoft Office Open XML Format document (23500/1/4) - 38.8% (.ZIP) Open Packaging Conventions container (17500/1/4) - 8.8% (.ZIP) ZIP compressed archive (4000/1) items: type: string type: array vendor_intel: $ref: '#/components/schemas/MalwareSampleVendorIntel' required: - anonymous - file_name - file_size - file_type_mime - first_seen - intelligence - md5_hash - reporter - sha1_hash - sha256_hash - sha3_384_hash - ssdeep type: object MalwareSampleComment: description: A comment made by a user on a malware sample. properties: comment: description: The escaped comment text itself. example: This malware is bad! type: string date_added: description: Timestamp when this comment has been made (RFC3339). example: "2025-03-30T19:10:50Z" format: date-time type: string display_name: description: Twitter display name. example: username type: string id: description: Unique ID that identifies this comment. example: 102110 format: int64 type: integer twitter_handle: description: Twitter handle who wrote this comment. example: username type: string required: - date_added - comment type: object MalwareSampleFileInformation: description: File information about the malware file sample. properties: context: description: The context label. example: dropped_by_md5 type: string value: description: The context value. example: 6e11af9a2132859a07b369d52ce5ca69 type: string required: - context - value type: object MalwareSampleIntelligence: description: MalwareBazaar intelligence about the malware sample. properties: clamav: description: List of ClamAV detections (official and unofficial rules). example: - SecuriteInfo.com.Trojan.InjectNET.14.27839.30.UNOFFICIAL items: type: string type: array downloads: description: Number of downloads from MalwareBazaar. example: 239 format: int64 type: integer uploads: description: Number of uploads to MalwareBazaar. example: 1 format: int64 type: integer required: - downloads - uploads type: object MalwareSampleList: description: The paginated list of malware samples. properties: items: description: The list of malware samples. items: $ref: '#/components/schemas/MalwareSample' type: array meta: $ref: '#/components/schemas/Pagination' required: - items - meta type: object MalwareSampleOleInformation: description: Object Linking and Embedding (OLE) information about the malware file sample. properties: oleid: items: $ref: '#/components/schemas/MalwareSampleOleInformationOleId' type: array olevba: items: $ref: '#/components/schemas/MalwareSampleOleInformationOleVba' type: array type: object MalwareSampleOleInformationOleId: description: "Results from [oleid](https://github.com/decalage2/oletools/wiki/oleid) - a tool for analyzing OLE files to detect \nspecific characteristics usually found in malicious files.\n" properties: application_name: description: | The name of the application that created the file, if retrievable from metadata (e.g., “Microsoft Word 97–2003”). example: Microsoft Word type: string encrypted: description: | Indicates whether the file is encrypted or password-protected, which can hinder analysis of its content. example: false type: boolean excel: description: True if the file appears to be a Microsoft Excel workbook. example: false type: boolean flash_objects: description: | True if the file contains embedded Flash objects, which are considered risky as they can execute code. example: false type: boolean has_summaryinfo_stream: description: "Shows whether the file contains a SummaryInformation stream, which stores standard metadata such as title, \nauthor, and creation date.\n" example: false type: boolean maldoc_score: description: "A heuristic score from 0 to 100 reflecting how suspicious the document is for being a malicious document (maldoc). \nHigher scores mean higher risk.\n" example: 5 format: int64 type: integer objectpool: description: "Indicates if the file contains an ObjectPool storage, which holds embedded OLE objects (e.g., an Excel sheet \nembedded in Word). These can hide malicious payloads.\n" example: false type: boolean ole_format: description: "The overall file format. Common values include OLE (legacy binary Office formats like .doc, .xls, .ppt), \nOpenXML (newer .docx, .xlsx, .pptx), or Unknown.\n" example: OpenXML type: string powerpoint: description: True if the file appears to be a Microsoft PowerPoint presentation. example: false type: boolean vba_macros: description: "Shows whether the file contains VBA macros, which are often used for automation but also frequently exploited \nfor malware.\n" example: false type: boolean visio: description: True if the file appears to be a Microsoft Visio document. example: false type: boolean word: description: True if the file appears to be a Microsoft Word document. example: true type: boolean type: object MalwareSampleOleInformationOleVba: description: "Results from [olevba](https://github.com/decalage2/oletools/wiki/olevba) - a tool for extracting and analyzing VBA \nMacro source code from MS Office documents (OLE and OpenXML).\n" properties: description: description: A description of the detection. example: Runs when the Excel Workbook is opened type: string keyword: description: The keyword that triggered the detection. example: Workbook_Open type: string type: description: The type of the detection. example: AutoExec type: string type: object MalwareSampleVendorIntel: description: The collected threat intelligence from various vendors for the malware sample. properties: cape: $ref: '#/components/schemas/MalwareSampleVendorIntelCape' spamhaus_hbl: $ref: '#/components/schemas/MalwareSampleVendorIntelSpamhausHBL' type: object MalwareSampleVendorIntelCape: description: Dynamic malware analysis from [CAPE Sandbox](https://capesandbox.com/). properties: detection: description: The detection name of the malware sample. example: Azorult type: string link: description: The URL to the analysis report. example: https://www.capesandbox.com/analysis/72842/ type: string required: - link type: object MalwareSampleVendorIntelSpamhausHBL: description: File reputation from [Spamhaus Hash Blocklist (HBL)](https://www.spamhaus.org/hbl/). properties: detection: description: The detection label. example: suspicious type: string link: description: The link to the HBL. example: https://www.spamhaus.org/hbl/ format: uri type: string required: - link type: object Pagination: description: The metadata for a paginated response. properties: next_cursor: description: The cursor for retrieving the next page of results, to be used with the `after` query parameter. example: ABC type: string next_page: description: "The relative URI (path and queries) reference for the next page of results. It will contain the original request \nURI, but the `after` query parameter will point to the cursor for the next page (i.e. `next_cursor`). If omitted, \nthere are no subsequent pages. The example value is just an illustration; the actual value will depend on the \nplatform and resource requested.\n" example: /platform/v1/resource?after=123 type: string page_size: description: Number of items per page. example: 100 format: int64 maximum: 100 minimum: 1 type: integer total_items: description: Total number of items returned. example: 10 format: int64 minimum: 0 type: integer required: - page_size - total_items type: object Payload: description: URLhaus payload entry. properties: file_name: description: The payload file name, if available. example: bin.exe type: string file_size: description: File size in bytes. example: 135784 format: int64 type: integer file_type: description: File type guessed by URLhaus. example: exe type: string first_seen: description: The timestamp for when URLhaus first saw this file payload (RFC3339). example: "2019-01-19T01:27:04Z" format: date-time type: string imphash: description: The file's import hash, if available. example: 3b91ed9563d0f99f26b86bd20539306b type: string last_seen: description: The timestamp for when URLhaus last saw this file payload (RFC3339). example: "2019-01-19T02:11:26Z" format: date-time type: string magika: description: The file type (identified by Magika), if available. example: ELF type: string md5_hash: description: The file's MD5 hash. example: 59ce0baba11893f90527fc951ac69912 type: string sha256_hash: description: The file's SHA256 hash. example: 4293c1d8574dc87c58360d6bac3daa182f64f7785c9d41da5e0741d2b1817fc7 type: string signature: description: The malware family, if available. example: Adwind type: string ssdeep: description: The file's ssdeep hash, if available. example: 3072:biMYFJvw6Yh0b1gKobtCGCmCRlrisfrYm:fYFJvwe1gKCYVl2szN type: string telfhash: description: The file's [Trend Micro ELF Hash](https://github.com/trendmicro/telfhash), if available. example: t1dd211d716b2195266ea0cd9088eca7b2512c97072349df33cf31849c24140aeea3ac4f type: string tlsh: description: The file's tlsh hash, if available. example: 59D31322D3130C4FC02579FA7A2BE62A39873E6A24CE449C45F5D66A2FB7084ED71753 type: string urlhaus_download: description: | URL where you can download a copy of the file sample for the given payload. Note that samples expire 30 days after they are first seen so the URL may return a 404 if the sample has expired. example: https://api.spamhaus.com/urlhaus/v1/files/samples/4293c1d8574dc87c58360d6bac3daa182f64f7785c9d41da5e0741d2b1817fc7 format: uri type: string required: - file_size - file_type - first_seen - last_seen - md5_hash - sha256_hash - urlhaus_download type: object PayloadList: description: The paginated list of payloads. properties: items: description: The list of payloads. items: $ref: '#/components/schemas/Payload' type: array meta: $ref: '#/components/schemas/Pagination' required: - items - meta type: object PayloadListWithFamilyDetails: description: The paginated list of payloads. properties: items: description: The list of payloads. items: $ref: '#/components/schemas/Payload' type: array malware_family_details: $ref: '#/components/schemas/MalwareFamilyDetails' meta: $ref: '#/components/schemas/Pagination' required: - items - meta type: object SampleRevocation: description: | A sample MalwareBazaar no longer serves. A revocation asserts that the sample has been withdrawn from the dataset. For MalwareBazaar it usually asserts more than that: most withdrawals are samples the abuse.ch curators listed as false positives, meaning the file was judged not to be malicious after all. properties: malwarebazaar_reference: description: | Link to the MalwareBazaar entry. The page may no longer resolve once a sample has been withdrawn upstream. example: https://bazaar.abuse.ch/sample/3d929643ad39d4b4cbb1a0c0b0a56b0bd2a2e1a1c0f3b6c9d8e7f6a5b4c3d2e1/ format: uri type: string md5_hash: description: | The MD5 of the same sample, so a consumer that ingested it under this hash can retire its own record without a second lookup. example: 3444d9086e3b1c2d4e5f60718293a4b5 type: string reason: description: | Why the sample was withdrawn, as far as it is known. - `false_positive`: the abuse.ch curators listed the sample as a false positive. The file was judged not to be malicious. - `unspecified`: the sample was withdrawn with no reason recorded. This vocabulary differs from the other platforms' deliberately. Where ThreatFox and URLhaus cannot tell a false-positive removal from an expiry, MalwareBazaar records the two separately, so reporting `absent_upstream` here would discard the more useful fact. enum: - false_positive - unspecified example: false_positive type: string revoked_at: description: | When the sample was withdrawn, in RFC 3339 format. Ordering is by this value, then by an internal identifier to break ties. Ties are the rule rather than the exception: one withdrawal pass stamps every sample it touches with a single timestamp, and the first such pass withdrew over 1,700 samples at once. example: "2026-08-11T16:14:10Z" format: date-time type: string sha1_hash: description: The SHA-1 of the same sample. example: 5f3e2d1c0b9a8877665544332211ffeeddccbbaa type: string sha3_384_hash: description: The SHA3-384 of the same sample. example: 9a8b7c6d5e4f302112233445566778899aabbccddeeff00112233445566778899aabbccddeeff0011 type: string sha256_hash: description: | The SHA-256 of the withdrawn sample, and the key to retire it under. example: 3d929643ad39d4b4cbb1a0c0b0a56b0bd2a2e1a1c0f3b6c9d8e7f6a5b4c3d2e1 type: string required: - sha256_hash - md5_hash - sha1_hash - sha3_384_hash - revoked_at - reason type: object SampleRevocationList: description: | The paginated list of revoked samples, newest first. Shares its shape with the other abuse.ch revocation endpoints: the same envelope, the same `revoked_at` semantics and ordering, and the same pagination contract. The item identifier is each platform's own, because consumers withdraw records using the key they ingested them under — for MalwareBazaar that is the SHA-256. A withdrawal is not necessarily permanent: if the abuse.ch curators drop the false-positive listing behind it, the sample returns to service and stops appearing here. No reinstatement record is published, so an entry's disappearance from this list is the only trace of it. properties: items: description: The list of revoked samples. items: $ref: '#/components/schemas/SampleRevocation' type: array meta: $ref: '#/components/schemas/Pagination' required: - items - meta type: object Tag: description: A known tag in ThreatFox. properties: first_seen: description: The timestamp for when the tag was first seen (RFC3339). format: date-time type: string last_seen: description: The timestamp for when the tag was last seen (RFC3339). format: date-time type: string name: description: The name of the tag. example: exe type: string required: - name - first_seen - last_seen type: object TagDetails: description: Tag summary details - this is only available if the `tag` query was provided. properties: first_seen: description: The date and time the tag was first seen (RFC3339). format: date-time type: string last_seen: description: The date and time the tag was last seen (RFC3339). format: date-time type: string url_count: description: The total number of associated observed URLs/Payloads (depending on request). example: 124 format: int64 type: integer required: - first_seen - last_seen - url_count type: object Task: description: A task. properties: clamav_results: description: The matching ClamAV signatures. example: - SecuriteInfo.com.Trojan.GenericKD.47707798.UNOFFICIAL - TwinWave.EvilDoc.DOCXRSTRGOOD.MSHTA.210816.UNOFFICIAL - TwinWave.EvilDoc.Excel4DragoTrainingMontage.20210204.UNOFFICIAL - TwinWave.EvilDoc.DOCXSTRGOODXL4.HTTP - TwinWave.EvilDoc.Emotet46and2.20220119.UNOFFICIAL items: type: string type: array id: description: The YARAify task ID. example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string metadata: $ref: '#/components/schemas/TaskMetadata' static_results: items: $ref: '#/components/schemas/TaskStaticResult' type: array yaraify_parameters: $ref: '#/components/schemas/TaskParameters' required: - id - yaraify_parameters - metadata type: object TaskList: description: The paginated list of file metadata search results. properties: items: description: The list of tasks search results. items: $ref: '#/components/schemas/Task' type: array meta: $ref: '#/components/schemas/Pagination' required: - items - meta type: object TaskMetadata: description: The task metadata. properties: file_name: description: The name of the file. example: 4760000.dll type: string file_size: description: The size of the file in bytes. example: 143360 format: int64 type: integer file_type_mime: description: The MIME type of the file. example: application/x-dosexec type: string first_seen: description: The timestamp when the file was first seen (RFC3339). format: date-time type: string last_seen: description: The timestamp when the file was first seen (RFC3339). format: date-time type: string md5_hash: description: The MD5 hash of the file. example: 4e22717b48f2f75fcfd47531c780b218 type: string sha1_hash: description: The SHA1 hash of the file. example: 60b637e95b1f2d14faaa71085b7e26321bfeeb6d type: string sha3_384_hash: description: The SHA3-384 hash of the file. example: 47c1b3eba75573642582d47a4c2259bc0f76fd1ab6bc81ca364d361f1f6bbc8263d961d5a42ce68f7af91c3366727a4d type: string sha256_hash: description: The SHA256 hash of the file. example: 7f94107c9becbcc6ca42070fca7e1e63f29cdd85cbbd8953bbca32a1b4f91219 type: string sightings: description: The number of sightings of the file. example: 28453 format: int64 type: integer unpacked_files_count: description: The number of unpacked files. example: 1 format: int64 type: integer required: - file_name - sha256_hash - md5_hash - sha1_hash - sha3_384_hash - sightings - unpacked_files_count type: object TaskParameters: description: The task execution parameters. properties: clamav_scan: description: Whether a ClamAV scan is performed. type: boolean share_file: description: Whether the file is shared with the community. type: boolean unpack: description: Whether the file is unpacked. type: boolean required: - clamav_scan - unpack - share_file type: object TaskStaticResult: description: The file scan static analysis results. properties: author: description: The author of the YARA rule. example: Marc Rivero | McAfee ATR Team type: string description: description: The description of the YARA rule. example: Rule to detect unpacked Emotet type: string reference: description: An arbitrary reference provided by the author. example: https://github.com/naxonez/yaraRules/blob/master/AntiDebugging.yara type: string rule_matching_tlp: description: The Traffic Light Protocol (TLP) level of the matching YARA rule. example: AMBER type: string rule_name: description: The name of the YARA rule. example: MALW_emotet type: string rule_sharing_tlp: description: The Traffic Light Protocol (TLP) level of the YARA rule, set by the author. example: AMBER type: string yarahub_uuid: description: The UUIDv4 of the YARA rule in [YaraHub](https://yaraify.abuse.ch/yarahub/). format: uuid type: string required: - rule_name type: object ThreatType: description: A supported IOC and threat type mappings in ThreatFox. properties: description: description: A description of the IOC and threat type mapping. example: Domain name that delivers a malware payload type: string ioc_type: description: The type of IOC. example: domain type: string threat_type: description: The type of threat. example: payload_delivery type: string required: - ioc_type - threat_type - description type: object ThreatTypeList: description: The list of threat type mapping results. example: - description: URL that delivers a malware payload ioc_type: url threat_type: payload_delivery - description: Domain name that delivers a malware payload ioc_type: domain threat_type: payload_delivery items: $ref: '#/components/schemas/ThreatType' type: array Url: description: URLhaus URL entry. properties: blacklists: $ref: '#/components/schemas/UrlBlacklists' first_seen: description: The timestamp for when the malware URL was added to URLhaus (RFC3339). format: date-time type: string host: description: The extracted host of the malware URL (IP address or domain name/FQDN). example: 117.206.17.116 type: string id: description: The unique identifier of the URLhaus entry. example: 3481371 format: int64 type: integer larted: description: Indicates whether the malware URL has been reported to the hosting provider. example: true type: boolean last_online: description: When URL is offline, i.e. last timestamp of when the URL was serving malware. Omitted if the URL is online (RFC3339). format: date-time type: string reporter: description: The Twitter handle of the reporter that has reported this malware URL (or `anonymous`). example: geenensp type: string tags: description: A list of tags associated with the queried malware URL. example: - elf items: type: string type: array takedown_time_seconds: description: The take down time in seconds (how long did it take for the hosting provider to take down the malware site). Omitted if the malware URL has not been taken down. example: 6831 format: int64 type: integer threat: description: The threat corresponding to this malware URL. Only `malware_download` is supported currently. enum: - malware_download example: malware_download type: string url: description: Malware URL associated with the entry. example: http://117.206.17.116:45305/i format: uri type: string url_status: description: | The current status of the URL. Supported statuses: - `online`: The malware URL is active (online) and currently serving a payload. - `offline`: The malware URL is inactive (offline) and serving no payload. - `unknown`: The currently malware URL status could not be determined. enum: - online - offline - unknown example: online type: string urlhaus_reference: description: Link to URLhaus entry. example: https://urlhaus.abuse.ch/url/3481371/ format: uri type: string required: - id - urlhaus_reference - url - url_status - host - first_seen - threat - blacklists - reporter - larted - tags type: object UrlBlacklists: description: Blacklist status of the queried URL. The SURBL and Spamhaus DBL blacklists are checked. properties: spamhaus_dbl: description: | Spamhaus DBL blacklist status. Possible values are: - `spammer_domain`: The queried malware URL is a known spammer domain. - `phishing_domain`: The queried malware URL is a known phishing domain. - `botnet_cc_domain`: The queried malware URL is a known botnet C&C domain. - `abused_legit_spam`: The queried malware URL is a known compromised website used for spammer hosting. - `abused_legit_malware`: The queried malware URL is a known compromised website used for malware distribution. - `abused_legit_phishing`: The queried malware URL is a known compromised website used for phishing hosting. - `abused_legit_botnetcc`: The queried malware URL is a known compromised website used for botnet C&C hosting. - `abused_redirector`: The queried malware URL is a known abused redirector or URL shortener. - `not listed`: The queried malware URL is not listed on Spamhaus DBL. enum: - spammer_domain - phishing_domain - botnet_cc_domain - abused_legit_spam - abused_legit_malware - abused_legit_phishing - abused_legit_botnetcc - abused_redirector - not listed example: not listed type: string required: - spamhaus_dbl type: object UrlList: description: The paginated list of URLs. properties: items: description: The list of URLs. items: $ref: '#/components/schemas/Url' type: array meta: $ref: '#/components/schemas/Pagination' required: - items - meta type: object UrlListWithTags: description: The paginated list of URLs with optional tag filter. properties: items: description: The list of URLs. items: $ref: '#/components/schemas/Url' type: array meta: $ref: '#/components/schemas/Pagination' tag_details: $ref: '#/components/schemas/TagDetails' required: - items - meta type: object UrlRevocation: description: | A record that URLhaus no longer serves. A revocation asserts only that the entry has been withdrawn from the dataset — it is not a statement that the URL was benign, nor that it is now safe. Entries are withdrawn for several reasons, including removal by the community, expiry, and correction of a false positive, and the reason is not distinguished here. properties: id: description: The unique identifier of the URLhaus entry that was revoked. example: 3481371 format: int64 type: integer revoked_at: description: | When the entry was withdrawn, in RFC 3339 format. Ordering is by this value, then by `id` to break ties. Ties are common rather than exceptional: a bulk withdrawal stamps every entry it touches with a single timestamp. example: "2026-08-07T12:34:56Z" format: date-time type: string urlhaus_reference: description: Link to the URLhaus entry. example: https://urlhaus.abuse.ch/url/3481371/ format: uri type: string required: - id - revoked_at type: object UrlRevocationList: description: | The paginated list of revoked records, newest first. This is the shape the other abuse.ch platforms reuse for their own revocation endpoints: the same envelope, the same `revoked_at` semantics and ordering, and the same pagination contract. Only the item identifier differs, because each platform is keyed differently — URLhaus and ThreatFox by a numeric id, MalwareBazaar by hash — so each keeps the identifier its other endpoints already use. A revocation is not reversible information: if a withdrawal turns out to have been wrong and the record is reinstated, it stops appearing here without any event saying so. Treat this feed as a reason to re-check a record rather than as a permanent verdict on it. properties: items: description: The list of revoked records. items: $ref: '#/components/schemas/UrlRevocation' type: array meta: $ref: '#/components/schemas/Pagination' required: - items - meta type: object YaraRule: description: A YARA rule associated with the malware sample. properties: author: description: The author of the YARA rule associated with the malware sample. example: The DFIR Report type: string description: description: The description of the YARA rule. example: files - file ~tmp01925d3f.exe type: string reference: description: The reference of the YARA rule. example: https://thedfirreport.com format: uri type: string rule_name: description: The name of the YARA rule associated with the malware sample. example: cobalt_strike_tmp01925d3f type: string tlp: description: The TLP (Traffic Light Protocol) level of the YARA rule. example: WHITE type: string required: - rule_name type: object YaraRuleList: description: The paginated list of YARA rule matches associated with the malware sample. properties: items: description: The list of YARA rule matches associated with the malware sample. items: $ref: '#/components/schemas/YaraRule' type: array meta: $ref: '#/components/schemas/Pagination' required: - items - meta type: object YaraRuleMetadata: description: Metadata for a YARA rule. properties: author: description: The author of the YARA rule. example: John Doe type: string date_written: description: The date of when the YARA rule was written. format: date type: string description: description: The author-submitted short description of the YARA rule. example: detects DanaBot type: string first_seen: description: The timestamp when the file was first seen (RFC3339). example: "2022-05-01T08:10:52Z" format: date-time type: string malpedia_family: description: The malware family name using Malpedia naming scheme. example: win.danabot type: string rule_name: description: The name of the YARA rule. example: win_danabot type: string yarahub_author_twitter: description: The Twitter handle of the YARA rule author. example: '@viql' type: string yarahub_license: description: | The Creative Commons license under which the YARA rule is shared. Possible options are: - `CC0 1.0`: Public domain, no copyright. - `CC BY 4.0`: Attribution required. - `CC BY-SA 4.0`: Attribution required, share alike. - `CC BY-ND 4.0`: Attribution required, no derviatives. - `CC BY-NC 4.0`: Attribution required, no commercial. - `CC BY-NC-SA 4.0`: Attribution required, no commercial, share alike. - `CC BY-NC-ND 4.0`: Attribution required, no commercial, no derivatives. example: CC BY-SA 4.0 type: string yarahub_reference_link: description: The online HTTP reference for this YARA rule. example: https://test.ch/bla format: uri type: string yarahub_reference_md5: description: The MD5 hash of a sample (file) that should match this YARA rule. example: 8195d9c7b7193e9c63137d156df7b6f3 type: string yarahub_rule_matching_tlp: description: "This [TLP](https://www.first.org/tlp/) (Traffic Light Protocol) defines whether YARA matches of this rule should \nbe publicly visible or not.\n" example: TLP:WHITE type: string yarahub_rule_sharing_tlp: description: "This [TLP](https://www.first.org/tlp/) (Traffic Light Protocol) defines whether the YARA rule itself should be \nshared or not.\n" example: TLP:WHITE type: string yarahub_uuid: description: The UUIDv4 of the YARA rule in YARAhub. format: uuid type: string required: - rule_name type: object YaraRuleMetadataList: description: The paginated list of YARA rule metadata. properties: items: description: The list of YARA rule metadata. items: $ref: '#/components/schemas/YaraRuleMetadata' type: array meta: $ref: '#/components/schemas/Pagination' required: - items - meta type: object securitySchemes: ApiKeyParameter: description: | A non-expiring API key passed via the `api-key` URL query string which allows third-party tools (e.g. MISP) to access file export formats in cases where standard authentication headers are not supported. Please note that this key should be treated with the same level of security as a password. in: query name: api-key type: apiKey BearerJwt: bearerFormat: JSON Web Token (JWT) description: "The API uses JWTs (JSON Web Tokens) for authentication. To authenticate, include the JWT in the `Authorization` \nheader of your requests. The `Authorization` header should consist of the word `Bearer` followed by a space and \nthen the JWT itself. Please see the [Login](#tag/authentication/post/v1/login) documentation for more \ndetails.\n" scheme: Bearer type: http info: contact: name: Spamhaus Support url: https://portal.spamhaus.com/tickets/ description: "# \U0001F4D8 Introduction\n\nWelcome to the commercial-grade API for [abuse.ch](https://abuse.ch) Malware Data. This API provides unified, \nread-only access to technical malware data and enriched IOCs curated through abuse.ch's core platforms: \n- **Malware URLs** (URLhaus)\n- **Malware Files** (MalwareBazaar)\n- **Malware Indicators of Compromise** (ThreatFox)\n- **YARA Scan Results** (YARAify)\n\nPlease note that this API is query-only and does *not* support submissions; to submit data to the respective \nplatforms, visit [abuse.ch](https://abuse.ch).\n\nDesigned for security analysts, researchers, reverse malware engineers and automated systems, the API enables fast, \nstructured querying of indicators and threat intelligence, as well as file downloads for supported platforms:\n- **File Sample Downloads**: URLhaus, MalwareBazaar, and YARAify (ThreatFox does not currently support \nfile sample downloads).\n- **File Export Downloads**: URLhaus, ThreatFox, and MalwareBazaar (YARAify does not currently support \nfile export downloads).\n\nThis service has been developed in collaboration with [abuse.ch](https://abuse.ch) as part of our \n[ongoing Alliance](https://www.spamhaus.com/abuse-ch/) to make high-quality threat intelligence more accessible, \nrobust and operationally useful to the industry.\n\nPlease note that this API is query-only and does *not* support submissions; to submit data to the respective \nplatforms, visit [abuse.ch](https://abuse.ch).\n\nTo gain access or learn more, please get in touch with the Spamhaus Team.\n\n# ✨ What's New\n\nFor the latest updates, new features, and changes to the abuse.ch API, please visit our \n[Changelog](https://abusech-docs.spamhaus.com/changelog).\n\n# \U0001F680 Getting Started\n\n## 1. Get your abuse.ch API credentials \U0001F44B\n\nCredentials of both kinds are available from the Spamhaus\n[Customer Portal](https://portal.spamhaus.com). If you need help obtaining them, or have any\nother questions, please [raise a support ticket](https://portal.spamhaus.com/tickets/).\n\nThere are two ways to authenticate: a short-lived **JWT** sent in the `Authorization` header,\nor a non-expiring **API key** carried as a segment of the URL itself. Which you use depends on\nwhat your tooling is capable of rather than on which endpoint you are calling. Section 2 below\nexplains both and how to choose.\n\n## 2. Authenticate with the API \U0001F511\n\n### Choosing a method\n\n| Method | How it travels | Lifetime | Best for |\n| ----------------------- | ----------------------------- | ------------------------------ | ------------------------------------- |\n| JWT in a header | `Authorization: Bearer ` | 24 hours, then re-authenticate | anything that can set HTTP headers |\n| API key in the URL path | a segment of the URL itself | does not expire | tooling that accepts only a plain URL |\n\n**Prefer the JWT wherever your tooling can set headers.** A credential placed in a URL is\nrecorded by every proxy, gateway and browser it passes through, and it does not expire, so an\nAPI key warrants the same care as a password. The URL-path option exists for the cases where a\nheader is simply not available - Microsoft Defender XDR custom detection rules using KQL\n`externaldata`, MISP feed ingestion, and similar - where the alternative would be not being\nable to use the API at all.\n\nBoth methods return exactly the same data, and a request costs the same against your quota\neither way.\n\n### JWT authentication\n\nThe login flow is documented in detail under the Login endpoint (/v1/login).\n\nJWTs are valid for 24 hours from the time of issue, after which re-authentication is required to obtain a new valid token.\n\nExample of login and JWT usage:\n![JWT authentication example](https://content.spamhaus.com/Example_of_login_and_JWT_usage.png)\n\nExample request using a JWT:\n```curl\ncurl 'https://api.spamhaus.com/threatfox/v1/iocs' -H 'Authorization: Bearer eyFhbGopOiYIUzI1NiIsInR5cCI6I...'\n```\n\n### API key authentication\n\nAn API key is passed as a segment of the URL, so no headers are needed at all.\n\nWhere the key sits in the path depends on the kind of endpoint:\n\n| Endpoint group | URL form | Available for |\n| ------------------- | ------------------------------------------------------- | ------------------------------------ |\n| Query endpoints | `/{platform}/v2/{api_key}/` | all four platforms |\n| Sample downloads | `/{platform}/v2/files/samples/{api_key}/{sha256_hash}` | URLhaus, MalwareBazaar, YARAify |\n| File export downloads | `/{platform}/v2/files/exports/{api_key}/{file_name}` | URLhaus, ThreatFox, MalwareBazaar |\n| MISP feed exports | `/{platform}/v1/files/exports/misp/{api_key}/{file_name}` | URLhaus, ThreatFox, MalwareBazaar |\n\nNote that on query endpoints the key comes **first**, immediately after the version, whereas on\ndownloads it comes after the file kind. The two gaps in the table are not limitations of\nURL-path authentication: ThreatFox has no sample-download endpoint at all, and YARAify has no\nfile-export endpoints at all, on either version.\n\nThe v1 file export endpoints additionally accept the key as an `?api-key=` query parameter.\nThis does not apply to the v2 forms above, where the key belongs in the path.\n\nExample request using an API key:\n```curl\ncurl 'https://api.spamhaus.com/threatfox/v2/sk_achp1_19AHTREQ4M.Xk3v.../iocs?since=2026-01-01'\n```\n\nExample of the same key downloading a sample:\n```curl\ncurl -O 'https://api.spamhaus.com/malwarebazaar/v2/files/samples/sk_achp1_19AHTREQ4M.Xk3v.../'\n```\n\nIf you are feeding a tool that ingests a whole file from a single URL - Microsoft Defender XDR\ncustom detection rules using KQL `externaldata`, MISP feeds, and similar - the **file export**\nendpoints are usually the better fit than the query endpoints. They serve a complete CSV or\nJSON file in one request, with no pagination to follow:\n```curl\ncurl 'https://api.spamhaus.com/threatfox/v2/files/exports/sk_achp1_19AHTREQ4M.Xk3v.../cscb.csv'\n```\n\n> [!note]\n> On paginated list endpoints, the `meta.next_page` value in the response repeats the URL you\n> called - including your API key - so that it can be requested directly by tooling that cannot\n> build a URL itself. Your key therefore appears in the response body as well as the request\n> URL. Bear this in mind if you log or cache API responses. If you would rather construct the\n> next URL yourself, use `meta.next_cursor`, which never contains the key.\n\n## 3. Execute API Requests \U0001F389\n\nThere are a number of ways you can interact with our APIs, based on your preferences, environment and organization's\nrequirements:\n\n- **From your Browser**: Using this documentation's API playground feature, you can click on the endpoints to \n execute requests directly from your browser. This is a great way to explore the API without needing any \n additional tools. You can also generate tool commands or code snippets for your preferred tooling or programming\n language/environment within this documentation page.\n- **CLI**: Use `cURL` or a similar CLI HTTP client tools to execute HTTP requests directly from the command line.\n- **Postman/Insomnia/etc**: Import the OpenAPI specification into your HTTP client tool of choice.\n- **Programming Languages**: Use the OpenAPI specification to generate client libraries in your preferred \n programming language (e.g. Python, JavaScript, Go, etc). You can likely find relevant tooling for your chosen \n language/environment on [OpenAPI Generator](https://openapi-generator.tech/).\n\nThe OpenAPI specification download links can be found at the top of this page in YAML or JSON formats.\n\n# \U0001F4BB Usage Notes\n\n## Pagination\n\nMost search/list endpoints support pagination to manage large result sets. We use cursor-based pagination, which is \ndocumented in the relevant endpoint sections as well as in the [Pagination](#model/pagination) schema.\n\nIn summary, paginated responses contain a `meta` object with pagination details, including `next_page` and \n`next_cursor` fields which can be used to fetch the next page of results. To retrieve subsequent pages, you can use \nthe `next_page` field which contains the original request URI, amended with the `after` query parameter pointing to \nthe next page. Alternatively, you can manually set the `after` query parameter to the `next_cursor` value in your \nnext request. Along with the `after` parameter, you must also provide all of the original query parameters that you \nprovided in the initial request, i.e. `page_size`, filter parameters like `tag`, etc.\n\n## HTTP Statuses\n\nFor search/list endpoints, if no results are found matching the search criteria, a `200 OK` response is returned \nwith an empty `items` array in the response body (unless specified otherwise). This indicates that the request was \nsuccessful, but no matching data was found. `404 Not Found` responses are generally reserved for cases where a \nspecific resource is requested by a unique identifier which does not exist (e.g. ID, hash).\n\n# \U0001F917 Support\n\nIf you have any questions, need assistance, or would like to report issues, please reach out to the Technical\nSupport team via the [Customer Portal](https://portal.spamhaus.com).\n" title: abuse.ch API version: 1.13.4 x-logo: altText: Spamhaus Technology | abuse.ch url: https://www.spamhaus.com/custom-content/themes/spamhauscom/assets/img/svg/logo-abuse.svg openapi: 3.0.3 paths: /malwarebazaar/v1/files/exports/{file_name}: get: description: | Data is available in multiple file formats, allowing users to work however their workflow requires—whether through automated scripts, dashboards, or manual examination. ### Dataset Types **Structured data formats (machine-friendly, for enrichment & SOAR)** - `.csv` (For ingestion into databases, analytics tools, and automated workflows. Can be used in SIEMs, TIP platforms, and SOAR pipelines, e.g., `recent.csv`, `cscb.csv`, `full.csv.zip`, `yara_rules.csv`) - `.json` (Ideal for automation, enrichment, and integration with SIEM or SOAR platforms, e.g., `recent.json`, `yara_rules.json`, `full.json.zip`) **Plain-text & list formats (for detection and blocklists)** - `.txt` (for quick scanning, blocklists, or feeding scripts, e.g., `md5_recent.txt`, `sha1_recent.txt`, `sha256_recent.txt`) **Hash-focused datasets (malware-centric workflows)** - MD5/SHA256 lists (MD5/SHA1/SHA256 lists (to support malware research, triage, or automated enrichment, e.g., `md5_full.txt.zip`, `sha1_full.txt.zip`, `sha256_full.txt.zip` #### Code Signing Certificates Blocklist (CSCB) A blocklist consisting of Code Signing Certificates (CSCB) is available. CSCs are used by threat actors to sign malware. This dataset is regenerated every 5 minutes. More information about the CSCB is available in the [abuse.ch FAQs](https://bazaar.abuse.ch/faq/#cscb). #### YARA Rule Statistics YARA rule statistics include the number of malware samples that match a specific rule and the timestamp of the last hit. You can use these statistics to query the corresponding API endpoint for a specific YARA rule. This statistics datasets are generated hourly. #### Recent vs Full Datasets - The "recent" datasets (recent additions) include hashes for the last 48 hours and are regenerated every 5 minutes. - The "full" datasets (complete data dumps) contain all hashes and are regenerated hourly. ### Authentication File export endpoints support both *Bearer JWT* and *API Key* authentication methods. Requests are authenticated by API key via the `api-key` URL query parameter; this enables 3rd party tooling to download export files when authentication schemes such as Bearer JWT are not natively supported. operationId: malwareBazaarExportDownload parameters: - description: The name of the export file you want to download. in: path name: file_name required: true schema: enum: - cscb.csv - full.csv.zip - md5_full.txt.zip - md5_recent.txt - recent.csv - sha1_full.txt.zip - sha1_recent.txt - sha256_full.txt.zip - sha256_recent.txt - yara_rules.csv - yara_rules.json example: recent.csv type: string x-enum-descriptions: cscb.csv: Code Signing Certificates Blocklist in CSV format. full.csv.zip: The full dataset in CSV format, ZIP compressed. md5_full.txt.zip: The full dataset MD5 hashes in plain text format, ZIP compressed. md5_recent.txt: Recent MD5 hash additions in plain text format. recent.csv: Recent additions in CSV format. sha1_full.txt.zip: The full dataset SHA1 hashes in plain text format, ZIP compressed. sha1_recent.txt: Recent SHA1 hash additions in plain text format. sha256_full.txt.zip: The full dataset SHA256 hashes in plain text format, ZIP compressed. sha256_recent.txt: Recent SHA256 hash additions in plain text format. yara_rules.csv: YARA rule statistics in CSV format. yara_rules.json: YARA rule statistics in JSON format. responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - ApiKeyParameter: [] - BearerJwt: [] summary: Download Export File (v1) tags: - MalwareBazaar x-badges: - name: New position: before x-internal: true /malwarebazaar/v1/files/samples/{sha256_hash}: get: description: "Download sample file by SHA256 hash.\n\n- Files are zipped using AES128 encryption and protected with the password `infected` for security purposes. If \nyou receive an `unsupported compression type 99` error when trying to unzip, it is likely that your tool/library \ndoes not support AES encryption. Please switch to a different tool or library such as `7z` which does support it, \ne.g. `7z x -pinfected 9608954039df864624c7df090b3733abd2a67680ebef3b74bc4ecf429482f463`\n- The decompressed files will always have a `.bin` extension, regardless of their original file type. This is done\nto prevent accidental execution of potentially malicious files. You can find the original file type via the API.\n- We have a minimum 1 month retention period for files. If you attempt to request files older than that, you may\nreceive a `404 Not Found` response.\n" operationId: malwareBazaarSampleDownloadByHash parameters: - description: The SHA256 hash of the sample file you want to download. example: f7f8694df632a541576229d89fa136e016f311fffd152b736ff6e330e553ec9a in: path name: sha256_hash required: true schema: type: string responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Download Sample File tags: - MalwareBazaar /malwarebazaar/v1/revocations: get: description: | Returns samples MalwareBazaar no longer serves, newest first, so a consumer can withdraw records it previously ingested. Each is keyed by SHA-256 and carries the sample's other three hashes, so a consumer that ingested it under MD5 or SHA-1 can retire its own record without a second lookup. Most withdrawals are samples the abuse.ch curators listed as false positives, reported as `false_positive` — the file was judged not to be malicious. Unlike the other platforms, MalwareBazaar records this distinctly, so a false positive is not conflated with an expiry. ### A withdrawal can be reversed, but you will not be told Most withdrawals here follow the abuse.ch curators' false-positive listing. If the curators later drop that listing, the sample returns to service, so a withdrawal is not permanent. What you will not get is a signal that it happened. A reinstated sample simply stops appearing in this list: there is no reinstatement record and no field marking an entry as retracted, so a consumer that retired its own record on the strength of an entry here has no automatic way to learn the entry was later reversed. The other platforms' revocation feeds behave the same way. Reinstatement is deliberately conservative. It requires several separate readings of the false-positive list to agree that the listing is gone, and hours to have passed, so no single reading can release a sample; and it requires abuse.ch to still serve the sample, so one removed from MalwareBazaar altogether stays withdrawn whatever happens to its false-positive listing. Reversals are rare in practice. If your integration needs to act on reinstatements, raise it with us. Whether to publish them is still an open question, and what consumers actually need is what will settle it. ### Filtering by age Use `since` to fetch everything revoked after a given time, and `until` to bound the other end of the window. To retrieve revocations no older than a given age, set `since` to that point in time. ### Polling Results are ordered by `revoked_at`, then by an internal identifier to break ties. Ties are the rule rather than the exception: one withdrawal pass stamps every sample it touches with a single timestamp, and the first such pass withdrew over 1,700 samples at once — so a single `revoked_at` can span many pages. **Overlap your polling window rather than advancing `since` to exactly the newest `revoked_at` you have seen.** Withdrawing a sample twice is harmless for a consumer, so the overlap costs nothing, and it protects you against the boundary. Paginate with `after` within a window and only move `since` once a window is exhausted. Records are served only once they have settled, which adds a short delay of about a minute between a sample being withdrawn and appearing here. This is deliberate: a revocation's timestamp is taken when its transaction starts but the record becomes visible when that transaction commits, so serving the newest records immediately would let a consumer's cursor skip past a sample stamped earlier and committed later. operationId: malwareBazaarRevocations parameters: - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/SampleRevocationList' description: The request was successful, and the server has returned revocation records. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Get revocations list tags: - MalwareBazaar x-badges: - name: New position: before /malwarebazaar/v1/samples: get: description: "Returns a list of the most recently malware sample records, or a filtered list of the search results if one of the \nsupported search query parameters is provided. Only **one** of the search query parameters can be provided at a \ntime, where providing multiple will result in a `400 Bad Request` response.\n\nSupported search query parameters (optional and mutually exclusive):\n- `tag`\n- `signature`\n- `file_type`\n- `imphash`\n- `tlsh`\n- `telfhash`\n- `gimphash`\n- `dhash_icon`\n- `yara_rule`\n- `clamav`\n\nPagination query parameters are also supported (but are optional), and can be used to limit the number of results returned.\n\nThe optional `since` query parameter can be used to filter the results by the age of the malware sample. This is \nuseful for filtering out older samples that may no longer be relevant.\n" operationId: malwareBazaarSampleSearch parameters: - description: The tag to filter the malware samples by. Cannot be combined with the other search query parameters. examples: example tag: value: dll omitted: value: "" in: query name: tag required: false schema: type: string - description: The signature to filter the malware samples by. Cannot be combined with the other search query parameters. examples: example signature: value: Adware.Generic omitted: value: "" in: query name: signature required: false schema: type: string - description: "The file type to filter the malware samples by. Empty value returns results with unknown or undefined file type. \nCannot be combined with the other search query parameters.\n" examples: example file type: value: elf omitted: value: "" in: query name: file_type required: false schema: type: string - description: The Imphash (import hash) to filter the malware samples by. Cannot be combined with the other search query parameters. examples: example imphash: value: 001f79fcd3f02e15b6ce3a0f62930c1c omitted: value: "" in: query name: imphash required: false schema: type: string - description: The TLSH to filter the malware samples by. Cannot be combined with the other search query parameters. examples: example tlsh: value: T100019EDD64B557710548CD08E16FCA6C640A8EC022808FED6D8C1A7A79DEF207126B48 omitted: value: "" in: query name: tlsh required: false schema: type: string - description: The telfhash to filter the malware samples by. Cannot be combined with the other search query parameters. examples: example telfhash: value: t10001140c8e3463e1db3a1d996b2dfe76e1a130df0a168d778e00fd6a861ed426e01c0c omitted: value: "" in: query name: telfhash required: false schema: type: string - description: The gimphash to filter the malware samples by. Cannot be combined with the other search query parameters. examples: example gimphash: value: 207afdd0ad108c8f2417defdf57d9c355cacd646da60e988bfc1a020d5b2bf18 omitted: value: "" in: query name: gimphash required: false schema: type: string - description: The dhash icon to filter the malware samples by. Cannot be combined with the other search query parameters. examples: example icon dhash: value: "0000000000000104" omitted: value: "" in: query name: dhash_icon required: false schema: type: string - description: The YARA rule to filter associated malware samples by. Cannot be combined with the other search query parameters. examples: example YARA rule: value: win_remcos_g0 omitted: value: "" in: query name: yara_rule required: false schema: type: string - description: The ClamAV signature to filter the malware samples by. Cannot be combined with the other search query parameters. in: query name: clamav required: false schema: example: ditekSHen.MALWARE.Win.Trojan.QuasarStealer.UNOFFICIAL type: string - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/MalwareSampleList' description: The list of malware samples was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Search Malware Samples tags: - MalwareBazaar /malwarebazaar/v1/samples/{hash}: get: description: Returns a single malware sample given its hash. operationId: malwareBazaarSampleGet parameters: - description: The hash of the malware sample to look up. This can be a SHA256, MD5, SHA3-384 or SHA1 hash. example: 55b34394408a316445b17c9552066d95516b155bbea94ac3dca205d1d5fabb30 in: path name: hash required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/MalwareSample' description: The request was successful, and the server has returned the malware sample. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Get Malware Sample by Hash tags: - MalwareBazaar /malwarebazaar/v1/samples/{hash}/matches: get: description: Returns a list of YARA rule matches associated with the malware sample hash. operationId: malwareBazaarSampleRuleMatchesList parameters: - description: | The hash of the malware sample to find YARA rule matches for. This can be a SHA256, MD5, SHA3-384 or SHA1 hash. example: 6a19622efa2574329528491472e1d2fe655ad103a9fa3396457875dfdab1f7ad in: path name: hash required: true schema: type: string - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/YaraRuleList' description: The request was successful, and the server has returned the requested data. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Get YARA Rule Matches by Malware Sample Hash tags: - MalwareBazaar /malwarebazaar/v2/{api_key}/revocations: get: description: | Identical to [Get revocations list](#tag/malwarebazaar/get/malwarebazaar/v1/revocations), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: malwareBazaarRevocationsWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/SampleRevocationList' description: The request was successful, and the server has returned revocation records. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Get revocations list (API key in URL) tags: - MalwareBazaar x-badges: - name: New position: before /malwarebazaar/v2/{api_key}/samples: get: description: | Identical to [Search Malware Samples](#tag/malwarebazaar/get/malwarebazaar/v1/samples), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: malwareBazaarSampleSearchWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: The tag to filter the malware samples by. Cannot be combined with the other search query parameters. examples: example tag: value: dll omitted: value: "" in: query name: tag required: false schema: type: string - description: The signature to filter the malware samples by. Cannot be combined with the other search query parameters. examples: example signature: value: Adware.Generic omitted: value: "" in: query name: signature required: false schema: type: string - description: | The file type to filter the malware samples by. Empty value returns results with unknown or undefined file type. Cannot be combined with the other search query parameters. examples: example file type: value: elf omitted: value: "" in: query name: file_type required: false schema: type: string - description: The Imphash (import hash) to filter the malware samples by. Cannot be combined with the other search query parameters. examples: example imphash: value: 001f79fcd3f02e15b6ce3a0f62930c1c omitted: value: "" in: query name: imphash required: false schema: type: string - description: The TLSH to filter the malware samples by. Cannot be combined with the other search query parameters. examples: example tlsh: value: T100019EDD64B557710548CD08E16FCA6C640A8EC022808FED6D8C1A7A79DEF207126B48 omitted: value: "" in: query name: tlsh required: false schema: type: string - description: The telfhash to filter the malware samples by. Cannot be combined with the other search query parameters. examples: example telfhash: value: t10001140c8e3463e1db3a1d996b2dfe76e1a130df0a168d778e00fd6a861ed426e01c0c omitted: value: "" in: query name: telfhash required: false schema: type: string - description: The gimphash to filter the malware samples by. Cannot be combined with the other search query parameters. examples: example gimphash: value: 207afdd0ad108c8f2417defdf57d9c355cacd646da60e988bfc1a020d5b2bf18 omitted: value: "" in: query name: gimphash required: false schema: type: string - description: The dhash icon to filter the malware samples by. Cannot be combined with the other search query parameters. examples: example icon dhash: value: "0000000000000104" omitted: value: "" in: query name: dhash_icon required: false schema: type: string - description: The YARA rule to filter associated malware samples by. Cannot be combined with the other search query parameters. examples: example YARA rule: value: win_remcos_g0 omitted: value: "" in: query name: yara_rule required: false schema: type: string - description: The ClamAV signature to filter the malware samples by. Cannot be combined with the other search query parameters. in: query name: clamav required: false schema: example: ditekSHen.MALWARE.Win.Trojan.QuasarStealer.UNOFFICIAL type: string - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/MalwareSampleList' description: The list of malware samples was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Search Malware Samples (API key in URL) tags: - MalwareBazaar x-badges: - name: New position: before /malwarebazaar/v2/{api_key}/samples/{hash}: get: description: | Identical to [Get Malware Sample by Hash](#tag/malwarebazaar/get/malwarebazaar/v1/samples/{hash}), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: malwareBazaarSampleGetWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: The hash of the malware sample to look up. This can be a SHA256, MD5, SHA3-384 or SHA1 hash. example: 55b34394408a316445b17c9552066d95516b155bbea94ac3dca205d1d5fabb30 in: path name: hash required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/MalwareSample' description: The request was successful, and the server has returned the malware sample. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Get Malware Sample by Hash (API key in URL) tags: - MalwareBazaar x-badges: - name: New position: before /malwarebazaar/v2/{api_key}/samples/{hash}/matches: get: description: | Identical to [Get YARA Rule Matches by Malware Sample Hash](#tag/malwarebazaar/get/malwarebazaar/v1/samples/{hash}/matches), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: malwareBazaarSampleRuleMatchesListWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: | The hash of the malware sample to find YARA rule matches for. This can be a SHA256, MD5, SHA3-384 or SHA1 hash. example: 6a19622efa2574329528491472e1d2fe655ad103a9fa3396457875dfdab1f7ad in: path name: hash required: true schema: type: string - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/YaraRuleList' description: The request was successful, and the server has returned the requested data. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Get YARA Rule Matches by Malware Sample Hash (API key in URL) tags: - MalwareBazaar x-badges: - name: New position: before /malwarebazaar/v2/files/exports/{api_key}/{file_name}: get: description: | Data is available in multiple file formats, allowing users to work however their workflow requires—whether through automated scripts, dashboards, or manual examination. ### Dataset Types **Structured data formats (machine-friendly, for enrichment & SOAR)** - `.csv` (For ingestion into databases, analytics tools, and automated workflows. Can be used in SIEMs, TIP platforms, and SOAR pipelines, e.g., `recent.csv`, `cscb.csv`, `full.csv.zip`, `yara_rules.csv`) - `.json` (Ideal for automation, enrichment, and integration with SIEM or SOAR platforms, e.g., `recent.json`, `yara_rules.json`, `full.json.zip`) **Plain-text & list formats (for detection and blocklists)** - `.txt` (for quick scanning, blocklists, or feeding scripts, e.g., `md5_recent.txt`, `sha1_recent.txt`, `sha256_recent.txt`) **Hash-focused datasets (malware-centric workflows)** - MD5/SHA256 lists (MD5/SHA1/SHA256 lists (to support malware research, triage, or automated enrichment, e.g., `md5_full.txt.zip`, `sha1_full.txt.zip`, `sha256_full.txt.zip` #### Code Signing Certificates Blocklist (CSCB) A blocklist consisting of Code Signing Certificates (CSCB) is available. CSCs are used by threat actors to sign malware. This dataset is regenerated every 5 minutes. More information about the CSCB is available in the [abuse.ch FAQs](https://bazaar.abuse.ch/faq/#cscb). #### YARA Rule Statistics YARA rule statistics include the number of malware samples that match a specific rule and the timestamp of the last hit. You can use these statistics to query the corresponding API endpoint for a specific YARA rule. This statistics datasets are generated hourly. #### Recent vs Full Datasets - The "recent" datasets (recent additions) include hashes for the last 48 hours and are regenerated every 5 minutes. - The "full" datasets (complete data dumps) contain all hashes and are regenerated hourly. ### Authentication This file export endpoint supports API Key authentication method. Requests are authenticated by API key via the `api_key` URL path parameter; this enables 3rd party tooling to download export files when authentication schemes such as Bearer JWT are not natively supported. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: malwareBazaarExportDownloadWithAPIKey parameters: - description: API key for authentication. in: path name: api_key required: true schema: type: string - description: The name of the export file you want to download. in: path name: file_name required: true schema: enum: - cscb.csv - full.csv.zip - full.json.zip - md5_full.txt.zip - md5_recent.txt - recent.csv - recent.json - sha1_full.txt.zip - sha1_recent.txt - sha256_full.txt.zip - sha256_recent.txt - yara_rules.csv - yara_rules.json example: recent.csv type: string x-enum-descriptions: cscb.csv: Code Signing Certificates Blocklist in CSV format. full.csv.zip: The full dataset in CSV format, ZIP compressed. full.json.zip: The full dataset in JSON format, ZIP compressed. md5_full.txt.zip: The full dataset MD5 hashes in plain text format, ZIP compressed. md5_recent.txt: Recent MD5 hash additions in plain text format. recent.csv: Recent additions in CSV format. recent.json: Recent additions in JSON format. sha1_full.txt.zip: The full dataset SHA1 hashes in plain text format, ZIP compressed. sha1_recent.txt: Recent SHA1 hash additions in plain text format. sha256_full.txt.zip: The full dataset SHA256 hashes in plain text format, ZIP compressed. sha256_recent.txt: Recent SHA256 hash additions in plain text format. yara_rules.csv: YARA rule statistics in CSV format. yara_rules.json: YARA rule statistics in JSON format. responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Download Export File(s) tags: - MalwareBazaar x-badges: - name: New position: before /malwarebazaar/v2/files/exports/misp/{api_key}/{file_name}: get: description: "Indicators of compromise (IOCs) from the MalwareBazaar platform are available as MISP events. New MISP events are \ngenerated daily.\n\n### MISP File Types\n\n- Each `UUID.json` file contains the MISP data for a single event and all of its associated indicators.\n- `manifest.json` is a summary file that lists every event file included in the collection, allowing MISP instances \nto see what events are available without downloading every full event file.\n\n### Authentication\n\nThis file export endpoint supports API Key authentication method. Requests are authenticated by\nAPI key via the `api_key` URL path parameter; this enables 3rd party tooling to download export files when\nauthentication schemes such as Bearer JWT are not natively supported.\n\nFor full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-).\n" operationId: malwareBazaarExportMispDownloadWithAPIKey parameters: - description: API key for authentication. in: path name: api_key required: true schema: type: string - description: The name of the MISP export file or manifest you want to download. examples: MISP export: value: 59ae1aef-33f8-4e20-bfcc-98fea6f32c21.json manifest: value: manifest.json in: path name: file_name required: true schema: type: string responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Download MISP Export File tags: - MalwareBazaar x-badges: - name: New position: before /malwarebazaar/v2/files/samples/{api_key}/{sha256_hash}: get: description: | Identical to [Download Sample File](#tag/malwarebazaar/get/malwarebazaar/v1/files/samples/{sha256_hash}), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: malwareBazaarSampleDownloadByHashWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: The SHA256 hash of the sample file you want to download. example: f7f8694df632a541576229d89fa136e016f311fffd152b736ff6e330e553ec9a in: path name: sha256_hash required: true schema: type: string responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Download Sample File (API key in URL) tags: - MalwareBazaar x-badges: - name: New position: before /threatfox/v1/families: get: description: "Returns a paginated list of Malware Families search results. If you submit IOCs to ThreatFox, you need to specify \nthe corresponding Malware Family, which can be identified via this endpoint. ThreatFox uses the Malware Family \nlabels from [Malpedia](https://malpedia.caad.fkie.fraunhofer.de/).\n\nBy default, all Malware Families are returned. You can search for specific Malware Families by providing the\n`malware_family` query parameter. You can also filter results by their malware platform using the `platform` query \nparameter. Finally, you can combine the `malware_family` and `platform` parameters to search for a specific Malware\nFamily within a given platform.\n" operationId: threatfoxMalwareFamilySearch parameters: - description: The name of the Malware Family label to search for. in: query name: malware_family required: false schema: example: fastcash type: string - description: The malware platform to filter results by. in: query name: platform required: false schema: example: win type: string - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/MalwareFamilyList' description: The list of Malware Family search matches. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Search Malware Families tags: - ThreatFox /threatfox/v1/files/exports/{file_name}: get: description: "ThreatFox offers exports for Indicators of Compromise (IOCs) in various formats.\n\nMultiple export formats are available—30, to be precise—for our Indicators of Compromise (IOCs) files. Generated to \nsupport easy integration across tools and workflows—from SIEM and IDS/IPS platforms to scripts and automation \npipelines.\n\n**Structured data format (machine-friendly, for enrichment & SOAR)**\n- `.json` (context-rich for SIEM, SOAR, TIP platforms, and automation workflows, e.g., `recent.json`, \n`domains_recent.json`,` ip_port_recent.json`, `urls_recent.json`, `md5_recent.json`, `sha256_recent.json`)\n- `.csv` (for database ingestion, analytics, and bulk processing workflows, e.g., `recent.csv`, \n`domains_recent.csv`, `ip_port_recent.csv`, `urls_recent.csv`, `md5_recent.csv`, `sha256_recent.csv`)\n- `.zip` (bundled CSV/JSON datasets to support the above needs, e.g., `full.json.zip`, `domains_full.json.zip`, \n`ip_port_full.json.zip`, `urls_full.csv.zip`, `md5_full.csv.zip`, `sha256_full.csv.zip`)\n\n**Plain-text & list formats (for detection and blocklists)**\n- `.txt` (Hosts-file style domain blocklist for DNS sinkholing and endpoint enforcement, e.g., `hostfile.txt`)\n- `.rpz` (DNS Response Policy Zone file for DNS-layer enforcement, e.g., `threatfox.rpz`)\n\n**Detection and security tool-specific formats**\n- .`rules` (Native Suricata IDS/IPS rule format for network-based detection, e.g., `threatfox_suricata.rules`)\n- `.tar.gz` (Bundled Suricata detection rule archive for streamlined deployment, e.g., `threatfox_suricata.tar.gz`)\n\n**Hash-focused datasets (malware-centric workflows)**\n- MD5/SHA256 lists (Hash indicators optimised for malware detection, EDR matching, sandbox correlation, and \nretro-hunting workflows, e.g, `md5_full.csv.zip`, `md5_full.json.zip`, `sha256_recent.csv`, `sha256_recent.json`)\n\n> [!note]\n> Please note: IOCs older than 6 months are excluded from exports. This is to avoid false positives, particularly \n> in cloud-based environments, where assets (e.g., IP addresses) frequently change ownership.\n\n### Dataset Types\n\n#### Host File\n\nSome commercial and open-source security software (such as [Pi-hole](https://pi-hole.net/)) can detect access to \ndomain names based on the host file format. For this purpose, we provide a list of domain-based IOCs. The host file \ncontains the following datasets observed in the past 6 month which are regenerated every 5 minutes:\n- Payload delivery domains\n- Botnet C2 domains\n\n#### Suricata IDS Ruleset\n\nA ruleset containing all network-based Indicators of Compromise (IOCs) for \n[Suricata IDS](https://suricata-ids.org/). Our view is that IOCs have an expiration date, so to avoid false \npositives, we export only IOCs from the past 6 months. Please note that the ruleset has been tested with Suricata \nversion `6.0.0`. The ruleset is regenerated every 5 minutes.\n\n#### DNS Response Policy Zone (RPZ)\n\nA DNS Response Policy Zone (RPZ) allows you to block the resolution of certain domain names on your DNS resolver. \nThis file offers the domain-based IOC domain names observed over the last 6 months and provides them in an RPZ \ndataset. More information about DNS RPZ is available at https://www.spamhaus.com/faqs/response-policy-zones/. \nThe RPZ zone file is regenerated every 5 minutes.\n\n#### JSON & CSV Exports\n\nThe \"recent\" datasets include IOCs for the last 48 hours and are regenerated every 5 minutes. The \"full\" data \nexports include all IOCs and are zip compressed; they are regenerated hourly.\n\n### Authentication\n\nFile export endpoints support both *Bearer JWT* and *API Key* authentication methods. Requests are authenticated by\nAPI key via the `api-key` URL query parameter; this enables 3rd party tooling to download export files when\nauthentication schemes such as Bearer JWT are not natively supported.\n" operationId: threatfoxExportDownload parameters: - description: The name of the export file you want to download. in: path name: file_name required: true schema: enum: - domains_full.csv.zip - domains_full.json.zip - domains_recent.csv - domains_recent.json - full.csv.zip - full.json.zip - hostfile.txt - ip_port_full.csv.zip - ip_port_full.json.zip - ip_port_recent.csv - ip_port_recent.json - md5_full.csv.zip - md5_full.json.zip - md5_recent.csv - md5_recent.json - recent.csv - recent.json - sha256_full.csv.zip - sha256_full.json.zip - sha256_recent.csv - sha256_recent.json - threatfox.rpz - threatfox_suricata.rules - threatfox_suricata.tar.gz - urls_full.csv.zip - urls_full.json.zip - urls_recent.csv - urls_recent.json example: recent.json type: string x-enum-descriptions: domains_full.csv.zip: The full domain dataset in CSV format, ZIP compressed. domains_full.json.zip: The full domain dataset in JSON format, ZIP compressed. domains_recent.csv: Recent domain additions (last 48 hours) in CSV format. domains_recent.json: Recent domain additions (last 48 hours) in JSON format. full.csv.zip: The full dataset in CSV format, ZIP compressed. full.json.zip: The full dataset in JSON format, ZIP compressed. hostfile.txt: Host file format dataset containing domain-based IOCs. ip_port_full.csv.zip: The full IP:Port dataset in CSV format, ZIP compressed. ip_port_full.json.zip: The full IP:Port dataset in JSON format, ZIP compressed. ip_port_recent.csv: Recent IP:Port additions (last 48 hours) in CSV format. ip_port_recent.json: Recent IP:Port additions (last 48 hours) in JSON format. md5_full.csv.zip: The full MD5 hash dataset in CSV format, ZIP compressed. md5_full.json.zip: The full MD5 hash dataset in JSON format, ZIP compressed. md5_recent.csv: Recent MD5 hash additions (last 48 hours) in CSV format. md5_recent.json: Recent MD5 hash additions (last 48 hours) in JSON format. recent.csv: Recent additions (last 48 hours) in CSV format. recent.json: Recent additions (last 48 hours) in JSON format. sha256_full.csv.zip: The full SHA256 hash dataset in CSV format, ZIP compressed. sha256_full.json.zip: The full SHA256 hash dataset in JSON format, ZIP compressed. sha256_recent.csv: Recent SHA256 hash additions (last 48 hours) in CSV format. sha256_recent.json: Recent SHA256 hash additions (last 48 hours) in JSON format. threatfox.rpz: DNS Response Policy Zone (RPZ) dataset containing domain-based IOCs. threatfox_suricata.rules: ThreatFox Suricata-specific IDS Ruleset. threatfox_suricata.tar.gz: ThreatFox Suricata-specific IDS Ruleset compressed in tar.gz format. urls_full.csv.zip: The full URL dataset in CSV format, ZIP compressed. urls_full.json.zip: The full URL dataset in JSON format, ZIP compressed. urls_recent.csv: Recent URL additions (last 48 hours) in CSV format. urls_recent.json: Recent URL additions (last 48 hours) in JSON format. responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - ApiKeyParameter: [] - BearerJwt: [] summary: Download Export File (v1) tags: - ThreatFox x-badges: - name: New position: before x-internal: true /threatfox/v1/iocs: get: description: "Returns a list of most recent Indicator of Compromise (IOC) records, or a filtered list of the search results if \none of the supported search query parameters is provided. Only **one** of the search query parameters can be \nprovided at a time, where providing multiple will result in a `400 Bad Request` response.\n\nSupported search query parameters (optional and mutually exclusive):\n- `ioc` (see related `exact_match` also)\n- `tag`\n- `malware_family`\n\nPagination query parameters are also supported (but are optional), and can be used to limit the number of results returned.\n" operationId: threatfoxIocSearch parameters: - description: The IOC you want to search for. Cannot be combined with the other search query parameters other than `exact_match`. in: query name: ioc required: false schema: example: www.siegania.com type: string - description: If `true`, the search will only return exact matches only. If `false`, the search will also return partial matches. Default `false`, i.e. partial IOC matches will be included. in: query name: exact_match required: false schema: example: false type: boolean - description: The tag you want to search for. Cannot be combined with the other search query parameters. in: query name: tag required: false schema: example: Magecart type: string - description: The malware family you want to search for. Cannot be combined with the other search query parameters. in: query name: malware_family required: false schema: example: Cobalt Strike type: string - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/IocList' description: The list of IOC matches was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Search Indicators of Compromise (IOCs) tags: - ThreatFox /threatfox/v1/iocs/{ioc_id}: get: description: Returns a single Indicator of Compromise (IOC) by ID. operationId: threatfoxIocGet parameters: - description: The unique identifier of the IOC. in: path name: ioc_id required: true schema: example: 1418919 format: int64 type: integer responses: "200": content: application/json: schema: $ref: '#/components/schemas/Ioc' description: The request was successful, and the server has returned the IOC. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Get Indicator of Compromise (IOC) by ID tags: - ThreatFox /threatfox/v1/revocations: get: description: | Returns IOCs ThreatFox no longer serves, newest first, so a consumer can withdraw entries it previously ingested. Each carries a `reason` where one is known. A revocation asserts only that the entry has been withdrawn from the dataset. It is **not** a statement that the indicator was benign or is now safe. Most withdrawals are simply an entry no longer appearing in the community dataset, reported as `absent_upstream`. That covers both expiry and false-positive removal, which upstream does not distinguish, so the two cannot be told apart here. ### Revocations can be reversed An entry withdrawn in error can be reinstated, and a reinstated entry simply stops appearing in this feed — there is no event announcing its return. It will not resurface at the top of the main IOC feed either, because that feed is ordered by the entry's own identifier rather than by when it was reinstated, so an incremental poll of recent entries misses it. A full re-synchronisation does return it. A consumer that withdraws entries on the strength of this feed should therefore re-synchronise periodically rather than relying on incremental updates alone, or it may keep an active indicator withdrawn indefinitely. This makes the guarantee asymmetric, and it is worth stating plainly: **we tell you when a record is withdrawn, and we do not tell you when a withdrawal was wrong.** A record you retired on the strength of this feed may be live again without anything here saying so. ### Entries withdrawn before revocation times were recorded A small number of historical IOCs were withdrawn before ThreatFox began recording when. They carry no revocation time and so never appear in this feed, which is ordered by it. A consumer building its first copy of the dataset should take the IOC list as its starting point rather than inferring absence from this endpoint. ### Filtering by age Use `since` to fetch everything revoked after a given time, and `until` to bound the other end of the window. To retrieve revocations no older than a given age, set `since` to that point in time. ### Polling Results are ordered by `revoked_at`, then by `id` to break ties. Ties are common rather than exceptional: a bulk withdrawal stamps every entry it touches with a single timestamp. **Overlap your polling window rather than advancing `since` to exactly the newest `revoked_at` you have seen.** Withdrawing an entry twice is harmless for a consumer, so the overlap costs nothing, and it protects you against the boundary. Paginate with `after` within a window and only move `since` once a window is exhausted. Records are served only once they have settled, which adds a short delay of about a minute between an entry being withdrawn and appearing here. This is deliberate: a revocation's timestamp is taken when its transaction starts but the record becomes visible when that transaction commits, so serving the newest records immediately would let a consumer's cursor skip past an entry stamped earlier and committed later. operationId: threatfoxRevocations parameters: - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/IocRevocationList' description: The request was successful, and the server has returned revocation records. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Get revocations list tags: - ThreatFox x-badges: - name: New position: before /threatfox/v1/tags: get: description: Returns a list of tags known to ThreatFox. operationId: threatfoxTagList responses: "200": content: application/json: schema: description: The list of tag results. example: - color: '#D984D4' first_seen: "2020-12-06T09:16:18Z" last_seen: "2020-12-08T13:36:27Z" name: exe - color: '#1BA0CD' first_seen: "2020-12-06T15:04:03Z" last_seen: "2020-12-06T15:04:03Z" name: js items: $ref: '#/components/schemas/Tag' type: array description: The list of tags was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: List Tags tags: - ThreatFox /threatfox/v1/threats: get: description: Returns a list of ThreatFox Indicator of Compromise (IOC) type and threat type mappings. operationId: threatfoxThreatTypesList responses: "200": content: application/json: schema: $ref: '#/components/schemas/ThreatTypeList' description: The list of IOC type and threat type mappings was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: List Mappings of Indicators of Compromise (IOC) to Threat Types tags: - ThreatFox /threatfox/v2/{api_key}/families: get: description: | Identical to [Search Malware Families](#tag/threatfox/get/threatfox/v1/families), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: threatfoxMalwareFamilySearchWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: The name of the Malware Family label to search for. in: query name: malware_family required: false schema: example: fastcash type: string - description: The malware platform to filter results by. in: query name: platform required: false schema: example: win type: string - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/MalwareFamilyList' description: The list of Malware Family search matches. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Search Malware Families (API key in URL) tags: - ThreatFox x-badges: - name: New position: before /threatfox/v2/{api_key}/iocs: get: description: | Identical to [Search Indicators of Compromise (IOCs)](#tag/threatfox/get/threatfox/v1/iocs), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: threatfoxIocSearchWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: The IOC you want to search for. Cannot be combined with the other search query parameters other than `exact_match`. in: query name: ioc required: false schema: example: www.siegania.com type: string - description: If `true`, the search will only return exact matches only. If `false`, the search will also return partial matches. Default `false`, i.e. partial IOC matches will be included. in: query name: exact_match required: false schema: example: false type: boolean - description: The tag you want to search for. Cannot be combined with the other search query parameters. in: query name: tag required: false schema: example: Magecart type: string - description: The malware family you want to search for. Cannot be combined with the other search query parameters. in: query name: malware_family required: false schema: example: Cobalt Strike type: string - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/IocList' description: The list of IOC matches was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Search Indicators of Compromise (IOCs) (API key in URL) tags: - ThreatFox x-badges: - name: New position: before /threatfox/v2/{api_key}/iocs/{ioc_id}: get: description: | Identical to [Get Indicator of Compromise (IOC) by ID](#tag/threatfox/get/threatfox/v1/iocs/{ioc_id}), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: threatfoxIocGetWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: The unique identifier of the IOC. in: path name: ioc_id required: true schema: example: 1418919 format: int64 type: integer responses: "200": content: application/json: schema: $ref: '#/components/schemas/Ioc' description: The request was successful, and the server has returned the IOC. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Get Indicator of Compromise (IOC) by ID (API key in URL) tags: - ThreatFox x-badges: - name: New position: before /threatfox/v2/{api_key}/revocations: get: description: | Identical to [Get revocations list](#tag/threatfox/get/threatfox/v1/revocations), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: threatfoxRevocationsWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/IocRevocationList' description: The request was successful, and the server has returned revocation records. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Get revocations list (API key in URL) tags: - ThreatFox x-badges: - name: New position: before /threatfox/v2/{api_key}/tags: get: description: | Identical to [List Tags](#tag/threatfox/get/threatfox/v1/tags), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: threatfoxTagListWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' responses: "200": content: application/json: schema: description: The list of tag results. example: - color: '#D984D4' first_seen: "2020-12-06T09:16:18Z" last_seen: "2020-12-08T13:36:27Z" name: exe - color: '#1BA0CD' first_seen: "2020-12-06T15:04:03Z" last_seen: "2020-12-06T15:04:03Z" name: js items: $ref: '#/components/schemas/Tag' type: array description: The list of tags was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: List Tags (API key in URL) tags: - ThreatFox x-badges: - name: New position: before /threatfox/v2/{api_key}/threats: get: description: | Identical to [List Mappings of Indicators of Compromise (IOC) to Threat Types](#tag/threatfox/get/threatfox/v1/threats), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: threatfoxThreatTypesListWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' responses: "200": content: application/json: schema: $ref: '#/components/schemas/ThreatTypeList' description: The list of IOC type and threat type mappings was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: List Mappings of Indicators of Compromise (IOC) to Threat Types (API key in URL) tags: - ThreatFox x-badges: - name: New position: before /threatfox/v2/files/exports/{api_key}/{file_name}: get: description: "ThreatFox offers exports for Indicators of Compromise (IOCs) in various formats.\n\nMultiple export formats are available—30, to be precise—for our Indicators of Compromise (IOCs) files. Generated to \nsupport easy integration across tools and workflows—from SIEM and IDS/IPS platforms to scripts and automation \npipelines.\n\n**Structured data format (machine-friendly, for enrichment & SOAR)**\n- `.json` (context-rich for SIEM, SOAR, TIP platforms, and automation workflows, e.g., `recent.json`, \n`domains_recent.json`,` ip_port_recent.json`, `urls_recent.json`, `md5_recent.json`, `sha256_recent.json`)\n- `.csv` (for database ingestion, analytics, and bulk processing workflows, e.g., `recent.csv`, \n`domains_recent.csv`, `ip_port_recent.csv`, `urls_recent.csv`, `md5_recent.csv`, `sha256_recent.csv`)\n- `.zip` (bundled CSV/JSON datasets to support the above needs, e.g., `full.json.zip`, `domains_full.json.zip`, \n`ip_port_full.json.zip`, `urls_full.csv.zip`, `md5_full.csv.zip`, `sha256_full.csv.zip`)\n\n**Plain-text & list formats (for detection and blocklists)**\n- `.txt` (Hosts-file style domain blocklist for DNS sinkholing and endpoint enforcement, e.g., `hostfile.txt`)\n- `.rpz` (DNS Response Policy Zone file for DNS-layer enforcement, e.g., `threatfox.rpz`)\n\n**Detection and security tool-specific formats**\n- .`rules` (Native Suricata IDS/IPS rule format for network-based detection, e.g., `threatfox_suricata.rules`)\n- `.tar.gz` (Bundled Suricata detection rule archive for streamlined deployment, e.g., `threatfox_suricata.tar.gz`)\n\n**Hash-focused datasets (malware-centric workflows)**\n- MD5/SHA256 lists (Hash indicators optimised for malware detection, EDR matching, sandbox correlation, and \nretro-hunting workflows, e.g, `md5_full.csv.zip`, `md5_full.json.zip`, `sha256_recent.csv`, `sha256_recent.json`)\n\n> [!note]\n> Please note: IOCs older than 6 months are excluded from exports. This is to avoid false positives, particularly \n> in cloud-based environments, where assets (e.g., IP addresses) frequently change ownership.\n\n### Dataset Types\n\n#### Host File\n\nSome commercial and open-source security software (such as [Pi-hole](https://pi-hole.net/)) can detect access to \ndomain names based on the host file format. For this purpose, we provide a list of domain-based IOCs. The host file \ncontains the following datasets observed in the past 6 month which are regenerated every 5 minutes:\n- Payload delivery domains\n- Botnet C2 domains\n\n#### Suricata IDS Ruleset\n\nA ruleset containing all network-based Indicators of Compromise (IOCs) for \n[Suricata IDS](https://suricata-ids.org/). Our view is that IOCs have an expiration date, so to avoid false \npositives, we export only IOCs from the past 6 months. Please note that the ruleset has been tested with Suricata \nversion `6.0.0`. The ruleset is regenerated every 5 minutes.\n\n#### DNS Response Policy Zone (RPZ)\n\nA DNS Response Policy Zone (RPZ) allows you to block the resolution of certain domain names on your DNS resolver. \nThis file offers the domain-based IOC domain names observed over the last 6 months and provides them in an RPZ \ndataset. More information about DNS RPZ is available at https://www.spamhaus.com/faqs/response-policy-zones/. \nThe RPZ zone file is regenerated every 5 minutes.\n\n#### JSON & CSV Exports\n\nThe \"recent\" datasets include IOCs for the last 48 hours and are regenerated every 5 minutes. The \"full\" data \nexports include all IOCs and are zip compressed; they are regenerated hourly.\n\n### Authentication\n\nThis file export endpoint supports API Key authentication method. Requests are authenticated by\nAPI key via the `api_key` URL path parameter; this enables 3rd party tooling to download export files when\nauthentication schemes such as Bearer JWT are not natively supported.\n\nFor full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-).\n" operationId: threatfoxExportDownloadWithAPIKey parameters: - description: API key for authentication. in: path name: api_key required: true schema: type: string - description: The name of the export file you want to download. in: path name: file_name required: true schema: enum: - domains_full.csv.zip - domains_full.json.zip - domains_recent.csv - domains_recent.json - full.csv.zip - full.json.zip - hostfile.txt - ip_port_full.csv.zip - ip_port_full.json.zip - ip_port_recent.csv - ip_port_recent.json - md5_full.csv.zip - md5_full.json.zip - md5_recent.csv - md5_recent.json - recent.csv - recent.json - sha256_full.csv.zip - sha256_full.json.zip - sha256_recent.csv - sha256_recent.json - threatfox.rpz - threatfox_suricata.rules - threatfox_suricata.tar.gz - urls_full.csv.zip - urls_full.json.zip - urls_recent.csv - urls_recent.json example: recent.json type: string x-enum-descriptions: domains_full.csv.zip: The full domain dataset in CSV format, ZIP compressed. domains_full.json.zip: The full domain dataset in JSON format, ZIP compressed. domains_recent.csv: Recent domain additions (last 48 hours) in CSV format. domains_recent.json: Recent domain additions (last 48 hours) in JSON format. full.csv.zip: The full dataset in CSV format, ZIP compressed. full.json.zip: The full dataset in JSON format, ZIP compressed. hostfile.txt: Host file format dataset containing domain-based IOCs. ip_port_full.csv.zip: The full IP:Port dataset in CSV format, ZIP compressed. ip_port_full.json.zip: The full IP:Port dataset in JSON format, ZIP compressed. ip_port_recent.csv: Recent IP:Port additions (last 48 hours) in CSV format. ip_port_recent.json: Recent IP:Port additions (last 48 hours) in JSON format. md5_full.csv.zip: The full MD5 hash dataset in CSV format, ZIP compressed. md5_full.json.zip: The full MD5 hash dataset in JSON format, ZIP compressed. md5_recent.csv: Recent MD5 hash additions (last 48 hours) in CSV format. md5_recent.json: Recent MD5 hash additions (last 48 hours) in JSON format. recent.csv: Recent additions (last 48 hours) in CSV format. recent.json: Recent additions (last 48 hours) in JSON format. sha256_full.csv.zip: The full SHA256 hash dataset in CSV format, ZIP compressed. sha256_full.json.zip: The full SHA256 hash dataset in JSON format, ZIP compressed. sha256_recent.csv: Recent SHA256 hash additions (last 48 hours) in CSV format. sha256_recent.json: Recent SHA256 hash additions (last 48 hours) in JSON format. threatfox.rpz: DNS Response Policy Zone (RPZ) dataset containing domain-based IOCs. threatfox_suricata.rules: ThreatFox Suricata-specific IDS Ruleset. threatfox_suricata.tar.gz: ThreatFox Suricata-specific IDS Ruleset compressed in tar.gz format. urls_full.csv.zip: The full URL dataset in CSV format, ZIP compressed. urls_full.json.zip: The full URL dataset in JSON format, ZIP compressed. urls_recent.csv: Recent URL additions (last 48 hours) in CSV format. urls_recent.json: Recent URL additions (last 48 hours) in JSON format. responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Download Export File(s) tags: - ThreatFox x-badges: - name: New position: before /threatfox/v2/files/exports/misp/{api_key}/{file_name}: get: description: "Indicators of compromise (IOCs) from the ThreatFox platform are available as MISP events. New MISP events are \ngenerated daily.\n\n### MISP File Types\n\n- Each `UUID.json` file contains the MISP data for a single event and all of its associated indicators.\n- `manifest.json` is a summary file that lists every event file included in the collection, allowing MISP instances \n to see what events are available without downloading every full event file.\n\n### Authentication\n\nThis file export endpoint supports API Key authentication method. Requests are authenticated by\nAPI key via the `api_key` URL path parameter; this enables 3rd party tooling to download export files when\nauthentication schemes such as Bearer JWT are not natively supported.\n\nFor full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-).\n" operationId: threatfoxExportMispDownloadWithAPIKey parameters: - description: API key for authentication. in: path name: api_key required: true schema: type: string - description: The name of the MISP export file or manifest you want to download. examples: MISP export: value: febedbda-d6ab-4ba2-881d-66ead125d9d8.json manifest: value: manifest.json in: path name: file_name required: true schema: type: string responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Download MISP Export File tags: - ThreatFox x-badges: - name: New position: before /urlhaus/v1/files/exports/{file_name}: get: description: "To operationalize this data quickly, multiple file formats are available for direct integration with a wide range \nof tools, from SIEMs and IDS platforms to spreadsheets and custom scripts. As an overview, these formats include:\n\n**Structured data formats (machine-friendly for enrichment & SOAR):**\n- `.json` (e.g., `online.json`, `recent.json`)\n- `.csv` (e.g., `online.csv`, `recent.csv`)\n- `.zip` (bundled CSV/JSON datasets, e.g., `full.json.zip`, `full.csv.zip`, or `payload.csv.zip`)\n- `.tar.gz` (bundled rules datasets, e.g., `urlhaus_ids.tar.gz`)\n\n**Plain-text & list formats (for fast detection and blocklists):**\n- `.txt` (e.g., `urls_full.txt`, `urls_recent.txt`)\n- Host lists (e.g., `hostfile.txt`)\n- RPZ zone format (e.g., `rpz.txt`)\n- Online/live feeds (e.g., `urls_online.txt`)\n\n**Detection & security tool–specific formats:**\n- Suricata rules (e.g., `urlhaus_ids_suricata.rules`, `urlhaus_ids_suricata.tar.gz`)\n- Generic IDS/IPS rules (e.g., `urlhaus_ids.rules`)\n- ClamAV signatures (e.g., `urlhaus_clamav.ndb`, `urlhaus_clamav.ndb.sha256`)\n\n### Dataset Types\n\n#### DNS Response Policy Zone (RPZ)\n\nA DNS Response Policy Zone (RPZ) allows you to block the resolution of certain domain names on your DNS resolver. \nabuse.ch extracts the domain names from malware URLs and offers them in an RPZ dataset; the zone file is regenerated \nevery 5 minutes. More information about DNS RPZ is available at \nhttps://www.spamhaus.com/faqs/response-policy-zones/. \n\nNote that, to reduce false positives, abuse.ch's RPZ includes only domain names associated with malware URLs that \nare either active (malware sites that currently serve a payload) or have been added to the URLhaus platform in the \npast 48 hours. Also, [Tranco Top 1M](https://tranco-list.eu/) is excluded from the RPZ dataset.\n\n#### Snort and Suricata IDS Ruleset\n\nIf you are using a network intrusion detection and prevention system (IDS/IPS), you can access a generic IDS \nruleset, or a Suricata-specific one, to identify network traffic towards known malware URLs. The dedicated Suricata \nruleset includes sticky buffers and delivers performance gains over the standard ruleset. Do also bear in mind that \nthe Suricata ruleset format is highly compatible with other system providers, such as Snort. \n\nThe ruleset will only trigger on the exact URL in an HTTP stream (HTTP GET request). The IDS rulesets are \nregenerated every 5 minutes.\n\nNote that due to the vast amount of malware URLs tracked by abuse.ch, these rulesets only include malware URLs that \nare either active (malware sites that currently serve a payload) or that have been added to the URLhaus platform in \nthe past 10 days. If you also want to monitor the offline malware URLs curated by abuse.ch, you will need a \ndifferent tool.\n\n#### Host File\n\nSome commercial and open-source security software (such as Pi-hole) can block access to domain names using the \nHosts file format. For this purpose, abuse.ch builds a list of domain names associated with malware URLs.\n\nNote that, to reduce false positives, the host file includes only domain names associated with malware URLs that \nare either active (malware sites that currently serve a payload) or have been added to the URLhaus platform in the \npast 48 hours. Also, [Tranco Top 1M](https://tranco-list.eu/) are excluded from this dataset.\n\n#### ClamAV Signatures\n\nabuse.ch generates a [ClamAV](https://www.clamav.net/) signature database of malware URLs, which is updated once per \nminute. This enables near-real-time detection of malware distribution sites (e.g., those used by StealC, Vidar, \netc.) on your email gateway or spam filter. Because the signature file contains only active malware distribution \nsites or those added to the URLhaus platform in the past 48 hours, a very low false-positive rate is achieved.\n\nIf you plan to use the ClamAV signatures, please update the signature file every minute to ensure the best \nprotection/catch rate. You can do so by setting up a cron job that runs the following script every minute. \n[An example shell script is available here](https://github.com/abusech/urlhaus/blob/master/clamav.sh).\n\nIt is also recommended that you either `REJECT` or `QUARANTINE` any email message that contains a link listed in \nthe ClamAV signature file. If you decide to `REJECT` emails containing listed URLs, the following page can be \nlinked to from the error message response that you send back to the user to support their understanding: \nhttps://urlhaus.abuse.ch/email-blocked/\n\nFurther information about the implementation of ClamAV can be found on the following websites:\n- [ClamAV: clamav-milter configuration](https://www.clamav.net/documents/configuration#clamav-milter)\n- [ClamAV: The ClamAV Plugin](https://wiki.apache.org/spamassassin/ClamAVPlugin)\n\n#### Plain Text Dumps\n\nThe plain-text URL list datasets are a dump of all malware URLs known to the URLhaus platform. They are composed of \none URL per line, which is useful if you want to use the dataset as an IOC (Indicator Of Compromise) list. You can \nmatch them against log files of your security perimeter, e.g., web proxy logs. You may also use it as a blocklist \nwith a low false positive rate. The Plain-Text URL List gets generated every 5 minutes.\n\n#### Collected Payloads\n\nabuse.ch regularly checks the content served by known URLs. This CSV (`payload.csv.zip`) contains all payloads \ncollected by the URLhaus platform, identified by a hash (MD5/SHA256 hash). Please consider that not all payloads \nare malicious. For example, a URL may no longer be malicious and no longer serve malware.\n\n#### Recent vs Active vs Full Datasets\n\n- **Recent**: An export of URLs recently added to URLhaus within the past 30 days.\n- **Active**: An export of active (online) malware distribution sites.\n- **Full**: An export of URLs that are either actively distributing malware or that have been added to URLhaus \nwithin the past 90 days.\n\n### Authentication\n\nFile export endpoints support both *Bearer JWT* and *API Key* authentication methods. Requests are authenticated by\nAPI key via the `api-key` URL query parameter; this enables 3rd party tooling to download export files when\nauthentication schemes such as Bearer JWT are not natively supported.\n" operationId: urlhausExportDownload parameters: - description: The name of the export file you want to download. in: path name: file_name required: true schema: enum: - full.csv.zip - full.json.zip - hostfile.txt - online.csv - online.json - payload.csv.zip - recent.csv - recent.json - rpz.txt - urlhaus_clamav.ndb - urlhaus_clamav.ndb.sha256 - urlhaus_ids.rules - urlhaus_ids.tar.gz - urlhaus_ids_suricata.rules - urlhaus_ids_suricata.tar.gz - urls_full.txt - urls_online.txt - urls_recent.txt example: recent.json type: string x-enum-descriptions: full.csv.zip: URLs that are either actively distributing malware or that have been added to URLhaus within the past 90 days, in CSV format, ZIP compressed. full.json.zip: URLs that are either actively distributing malware or that have been added to URLhaus within the past 90 days, in JSON format, ZIP compressed. hostfile.txt: Host file format dataset. online.csv: Active malware malware URLs in CSV format. online.json: Active malware malware URLs in JSON format. payload.csv.zip: Collected payloads in CSV format, ZIP compressed. recent.csv: Recent URL additions (last 30 days) in CSV format. recent.json: Recent URL additions (last 30 days) in JSON format. rpz.txt: DNS Response Policy Zone dataset. urlhaus_clamav.ndb: ClamAV signature database file. urlhaus_clamav.ndb.sha256: ClamAV SHA256 checksum file. urlhaus_ids.rules: URLhaus Snort/Suricata IDS Ruleset. urlhaus_ids.tar.gz: URLhaus Snort/Suricata IDS Ruleset compressed in tar.gz format. urlhaus_ids_suricata.rules: URLhaus Suricata-specific IDS Ruleset (using stick buffers). urlhaus_ids_suricata.tar.gz: URLhaus Suricata-specific IDS Ruleset (using stick buffers) compressed in tar.gz format. urls_full.txt: Full URL list in plain-text format. urls_online.txt: Active malware URL list in plain-text format. urls_recent.txt: Recent URL additions list (last 30 days) in plain-text format. responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - ApiKeyParameter: [] - BearerJwt: [] summary: Download Export File (v1) tags: - URLhaus x-badges: - name: New position: before x-internal: true /urlhaus/v1/files/samples/{sha256_hash}: get: description: "Download sample file by SHA256 hash.\n\n- Files are zipped using AES128 encryption and protected with the password `infected` for security purposes. If \nyou receive an `unsupported compression type 99` error when trying to unzip, it is likely that your tool/library \ndoes not support AES encryption. Please switch to a different tool or library such as `7z` which does support it, \ne.g. `7z x -pinfected 9608954039df864624c7df090b3733abd2a67680ebef3b74bc4ecf429482f463`\n- The decompressed files will always have a `.bin` extension, regardless of their original file type. This is done\nto prevent accidental execution of potentially malicious files. You can find the original file type via the API.\n- We have a minimum 1 month retention period for files. If you attempt to request files older than that, you may\nreceive a `404 Not Found` response.\n" operationId: urlhausSampleDownloadByHash parameters: - description: The SHA256 hash of the sample file you want to download. example: 4293c1d8574dc87c58360d6bac3daa182f64f7785c9d41da5e0741d2b1817fc7 in: path name: sha256_hash required: true schema: type: string responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Download Sample File tags: - URLhaus /urlhaus/v1/hosts: get: description: Returns information about recent hosts. operationId: urlhausHosts parameters: - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/HostsList' description: The request was successful, and the server has returned hosts records. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Get Hosts list tags: - URLhaus /urlhaus/v1/hosts/{host}: get: description: Returns information about a host. operationId: urlhausHostGet parameters: - $ref: '#/components/parameters/Host' responses: "200": content: application/json: schema: $ref: '#/components/schemas/HostDetails' description: The request was successful, and the server has returned the host record. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Get Host tags: - URLhaus /urlhaus/v1/hosts/{host}/urls: get: description: "Returns a list of URLs associated with the given host. \n\nPagination query parameters are supported (but are optional), and can be used to limit the number of results returned.\n" operationId: urlhausHostUrlsList parameters: - $ref: '#/components/parameters/Host' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/UrlList' description: The list of URL records was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: List URLs for a Host tags: - URLhaus /urlhaus/v1/payloads: get: description: "Returns a list of recent payloads (malware sample) seen by URLhaus. \n\nUse the `malware_family` query parameter to filter results by malware family signature. URLhaus tries to identify \nthe malware family of a payload (malware sample) served by malware URLs. Unlike tags, the malware family signature \ncannot be influenced by the reporter of the malware URL.\n\nPagination query parameters are also supported (but are optional), and can be used to limit the number of results returned.\n" operationId: urlhausPayloadSearch parameters: - description: The malware family signature to filter results by (case insensitive). If the malware family is invalid, a `404 Not Found` response is returned. in: query name: malware_family required: false schema: example: Mozi type: string - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/PayloadListWithFamilyDetails' description: The list of payloads was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Search Payloads tags: - URLhaus /urlhaus/v1/payloads/{hash}: get: description: | Returns information about a payload (malware sample) for a given hash (`md5` or `sha256`). operationId: urlhausPayloadGetByHash parameters: - $ref: '#/components/parameters/PayloadHash' responses: "200": content: application/json: schema: $ref: '#/components/schemas/Payload' description: The payload record was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Get Payload by Hash tags: - URLhaus /urlhaus/v1/payloads/{hash}/urls: get: description: "Returns a list of URLs associated with the given payload hash (`md5` or `sha256`). \n\nPagination query parameters are supported (but are optional), and can be used to limit the number of results returned.\n" operationId: urlhausPayloadUrlsList parameters: - $ref: '#/components/parameters/PayloadHash' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/UrlList' description: The list of URL records was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: List URLs for a Payload tags: - URLhaus /urlhaus/v1/revocations: get: description: | Returns records URLhaus no longer serves, newest first, so a consumer can withdraw entries it previously ingested. A revocation asserts only that the entry has been withdrawn from the dataset. It is **not** a statement that the URL was benign or is now safe. Entries are withdrawn for several reasons — removal by the community, expiry, correction of a false positive — and the reason is not distinguished here. ### Revocations can be reversed An entry withdrawn in error can be reinstated, and a reinstated entry simply stops appearing in this feed — there is no event announcing its return. It will not resurface at the top of the main URL feed either, because that feed is ordered by when an entry was *added* rather than when it was reinstated, so an incremental poll of recent additions misses it. A full re-synchronisation does return it. A consumer that withdraws entries on the strength of this feed should therefore re-synchronise periodically rather than relying on incremental updates alone, or it may keep an active malware URL withdrawn indefinitely. This makes the guarantee asymmetric, and it is worth stating plainly: **we tell you when a record is withdrawn, and we do not tell you when a withdrawal was wrong.** A record you retired on the strength of this feed may be live again without anything here saying so. ### Filtering by age Use `since` to fetch everything revoked after a given time, and `until` to bound the other end of the window. To retrieve revocations no older than a given age, set `since` to that point in time. ### Polling Results are ordered by `revoked_at`, then by `id` to break ties. Ties are common rather than exceptional: a bulk withdrawal stamps every entry it touches with a single timestamp. **Overlap your polling window rather than advancing `since` to exactly the newest `revoked_at` you have seen.** Withdrawing an entry twice is harmless for a consumer, so the overlap costs nothing, and it protects you against the boundary. Paginate with `after` within a window and only move `since` once a window is exhausted. Records are served only once they have settled, which adds a short delay of about a minute between an entry being withdrawn and appearing here. This is deliberate: a revocation's timestamp is taken when its transaction starts but the record becomes visible when that transaction commits, so serving the newest records immediately would let a consumer's cursor skip past an entry stamped earlier and committed later. operationId: urlhausRevocations parameters: - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/UrlRevocationList' description: The request was successful, and the server has returned revocation records. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Get revocations list tags: - URLhaus x-badges: - name: New position: before /urlhaus/v1/urls: get: description: "Returns a list of recent URL additions made to URLhaus. \n\nUse the `tag` query parameter to filter results by tag. Unlike malware family signatures, the tag can be influenced\nby the reporter of the malware URL.\n\nPagination query parameters are also supported (but are optional), and can be used to limit the number of results returned.\n" operationId: urlhausUrlSearch parameters: - description: The tag to filter results by (case insensitive). in: query name: tag required: false schema: example: elf type: string - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/UrlListWithTags' description: The list of URL records was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Search URLs tags: - URLhaus /urlhaus/v1/urls/{target_url}: get: description: Returns a single URL record for a given URL ID or encoded-URL string, including any relevant payload records. operationId: urlhausUrlGet parameters: - $ref: '#/components/parameters/TargetUrl' responses: "200": content: application/json: schema: $ref: '#/components/schemas/Url' description: The request was successful, and the server has returned the URL record. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Get URL tags: - URLhaus /urlhaus/v1/urls/{target_url}/payloads: get: description: | Returns a list of payloads (malware samples) associated with the given URL ID or encoded-URL string. Pagination query parameters are supported (but are optional), and can be used to limit the number of results returned. operationId: urlhausUrlPayloadsList parameters: - $ref: '#/components/parameters/TargetUrl' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/PayloadList' description: The list of payloads was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: List Payloads for a URL tags: - URLhaus /urlhaus/v2/{api_key}/hosts: get: description: | Identical to [Get Hosts list](#tag/urlhaus/get/urlhaus/v1/hosts), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: urlhausHostsWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/HostsList' description: The request was successful, and the server has returned hosts records. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Get Hosts list (API key in URL) tags: - URLhaus x-badges: - name: New position: before /urlhaus/v2/{api_key}/hosts/{host}: get: description: | Identical to [Get Host](#tag/urlhaus/get/urlhaus/v1/hosts/{host}), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: urlhausHostGetWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - $ref: '#/components/parameters/Host' responses: "200": content: application/json: schema: $ref: '#/components/schemas/HostDetails' description: The request was successful, and the server has returned the host record. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Get Host (API key in URL) tags: - URLhaus x-badges: - name: New position: before /urlhaus/v2/{api_key}/hosts/{host}/urls: get: description: | Identical to [List URLs for a Host](#tag/urlhaus/get/urlhaus/v1/hosts/{host}/urls), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: urlhausHostUrlsListWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - $ref: '#/components/parameters/Host' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/UrlList' description: The list of URL records was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: List URLs for a Host (API key in URL) tags: - URLhaus x-badges: - name: New position: before /urlhaus/v2/{api_key}/payloads: get: description: | Identical to [Search Payloads](#tag/urlhaus/get/urlhaus/v1/payloads), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: urlhausPayloadSearchWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: The malware family signature to filter results by (case insensitive). If the malware family is invalid, a `404 Not Found` response is returned. in: query name: malware_family required: false schema: example: Mozi type: string - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/PayloadListWithFamilyDetails' description: The list of payloads was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Search Payloads (API key in URL) tags: - URLhaus x-badges: - name: New position: before /urlhaus/v2/{api_key}/payloads/{hash}: get: description: | Identical to [Get Payload by Hash](#tag/urlhaus/get/urlhaus/v1/payloads/{hash}), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: urlhausPayloadGetByHashWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - $ref: '#/components/parameters/PayloadHash' responses: "200": content: application/json: schema: $ref: '#/components/schemas/Payload' description: The payload record was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Get Payload by Hash (API key in URL) tags: - URLhaus x-badges: - name: New position: before /urlhaus/v2/{api_key}/payloads/{hash}/urls: get: description: | Identical to [List URLs for a Payload](#tag/urlhaus/get/urlhaus/v1/payloads/{hash}/urls), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: urlhausPayloadUrlsListWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - $ref: '#/components/parameters/PayloadHash' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/UrlList' description: The list of URL records was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: List URLs for a Payload (API key in URL) tags: - URLhaus x-badges: - name: New position: before /urlhaus/v2/{api_key}/revocations: get: description: | Identical to [Get revocations list](#tag/urlhaus/get/urlhaus/v1/revocations), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: urlhausRevocationsWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/UrlRevocationList' description: The request was successful, and the server has returned revocation records. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Get revocations list (API key in URL) tags: - URLhaus x-badges: - name: New position: before /urlhaus/v2/{api_key}/urls: get: description: | Identical to [Search URLs](#tag/urlhaus/get/urlhaus/v1/urls), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: urlhausUrlSearchWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: The tag to filter results by (case insensitive). in: query name: tag required: false schema: example: elf type: string - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/UrlListWithTags' description: The list of URL records was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Search URLs (API key in URL) tags: - URLhaus x-badges: - name: New position: before /urlhaus/v2/{api_key}/urls/{target_url}: get: description: | Identical to [Get URL](#tag/urlhaus/get/urlhaus/v1/urls/{target_url}), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: urlhausUrlGetWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - $ref: '#/components/parameters/TargetUrl' responses: "200": content: application/json: schema: $ref: '#/components/schemas/Url' description: The request was successful, and the server has returned the URL record. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Get URL (API key in URL) tags: - URLhaus x-badges: - name: New position: before /urlhaus/v2/{api_key}/urls/{target_url}/payloads: get: description: | Identical to [List Payloads for a URL](#tag/urlhaus/get/urlhaus/v1/urls/{target_url}/payloads), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: urlhausUrlPayloadsListWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - $ref: '#/components/parameters/TargetUrl' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/PayloadList' description: The list of payloads was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: List Payloads for a URL (API key in URL) tags: - URLhaus x-badges: - name: New position: before /urlhaus/v2/files/exports/{api_key}/{file_name}: get: description: "To operationalize this data quickly, multiple file formats are available for direct integration with a wide range \nof tools, from SIEMs and IDS platforms to spreadsheets and custom scripts. As an overview, these formats include:\n\n**Structured data formats (machine-friendly for enrichment & SOAR):**\n- `.json` (e.g., `online.json`, `recent.json`)\n- `.csv` (e.g., `online.csv`, `recent.csv`)\n- `.zip` (bundled CSV/JSON datasets, e.g., `full.json.zip`, `full.csv.zip`, or `payload.csv.zip`)\n- `.tar.gz` (bundled rules datasets, e.g., `urlhaus_ids.tar.gz`)\n\n**Plain-text & list formats (for fast detection and blocklists):**\n- `.txt` (e.g., `urls_full.txt`, `urls_recent.txt`)\n- Host lists (e.g., `hostfile.txt`)\n- RPZ zone format (e.g., `rpz.txt`)\n- Online/live feeds (e.g., `urls_online.txt`)\n\n**Detection & security tool–specific formats:**\n- Suricata rules (e.g., `urlhaus_ids_suricata.rules`, `urlhaus_ids_suricata.tar.gz`)\n- Generic IDS/IPS rules (e.g., `urlhaus_ids.rules`)\n- ClamAV signatures (e.g., `urlhaus_clamav.ndb`, `urlhaus_clamav.ndb.sha256`)\n\n### Dataset Types\n\n#### DNS Response Policy Zone (RPZ)\n\nA DNS Response Policy Zone (RPZ) allows you to block the resolution of certain domain names on your DNS resolver. \nabuse.ch extracts the domain names from malware URLs and offers them in an RPZ dataset; the zone file is regenerated \nevery 5 minutes. More information about DNS RPZ is available at \nhttps://www.spamhaus.com/faqs/response-policy-zones/. \n\nNote that, to reduce false positives, abuse.ch's RPZ includes only domain names associated with malware URLs that \nare either active (malware sites that currently serve a payload) or have been added to the URLhaus platform in the \npast 48 hours. Also, [Tranco Top 1M](https://tranco-list.eu/) is excluded from the RPZ dataset.\n\n#### Snort and Suricata IDS Ruleset\n\nIf you are using a network intrusion detection and prevention system (IDS/IPS), you can access a generic IDS \nruleset, or a Suricata-specific one, to identify network traffic towards known malware URLs. The dedicated Suricata \nruleset includes sticky buffers and delivers performance gains over the standard ruleset. Do also bear in mind that \nthe Suricata ruleset format is highly compatible with other system providers, such as Snort. \n\nThe ruleset will only trigger on the exact URL in an HTTP stream (HTTP GET request). The IDS rulesets are \nregenerated every 5 minutes.\n\nNote that due to the vast amount of malware URLs tracked by abuse.ch, these rulesets only include malware URLs that \nare either active (malware sites that currently serve a payload) or that have been added to the URLhaus platform in \nthe past 10 days. If you also want to monitor the offline malware URLs curated by abuse.ch, you will need a \ndifferent tool.\n\n#### Host File\n\nSome commercial and open-source security software (such as Pi-hole) can block access to domain names using the \nHosts file format. For this purpose, abuse.ch builds a list of domain names associated with malware URLs.\n\nNote that, to reduce false positives, the host file includes only domain names associated with malware URLs that \nare either active (malware sites that currently serve a payload) or have been added to the URLhaus platform in the \npast 48 hours. Also, [Tranco Top 1M](https://tranco-list.eu/) are excluded from this dataset.\n\n#### ClamAV Signatures\n\nabuse.ch generates a [ClamAV](https://www.clamav.net/) signature database of malware URLs, which is updated once per \nminute. This enables near-real-time detection of malware distribution sites (e.g., those used by StealC, Vidar, \netc.) on your email gateway or spam filter. Because the signature file contains only active malware distribution \nsites or those added to the URLhaus platform in the past 48 hours, a very low false-positive rate is achieved.\n\nIf you plan to use the ClamAV signatures, please update the signature file every minute to ensure the best \nprotection/catch rate. You can do so by setting up a cron job that runs the following script every minute. \n[An example shell script is available here](https://github.com/abusech/urlhaus/blob/master/clamav.sh).\n\nIt is also recommended that you either `REJECT` or `QUARANTINE` any email message that contains a link listed in \nthe ClamAV signature file. If you decide to `REJECT` emails containing listed URLs, the following page can be \nlinked to from the error message response that you send back to the user to support their understanding: \nhttps://urlhaus.abuse.ch/email-blocked/\n\nFurther information about the implementation of ClamAV can be found on the following websites:\n- [ClamAV: clamav-milter configuration](https://www.clamav.net/documents/configuration#clamav-milter)\n- [ClamAV: The ClamAV Plugin](https://wiki.apache.org/spamassassin/ClamAVPlugin)\n\n#### Plain Text Dumps\n\nThe plain-text URL list datasets are a dump of all malware URLs known to the URLhaus platform. They are composed of \none URL per line, which is useful if you want to use the dataset as an IOC (Indicator Of Compromise) list. You can \nmatch them against log files of your security perimeter, e.g., web proxy logs. You may also use it as a blocklist \nwith a low false positive rate. The Plain-Text URL List gets generated every 5 minutes.\n\n#### Collected Payloads\n\nabuse.ch regularly checks the content served by known URLs. This CSV (`payload.csv.zip`) contains all payloads \ncollected by the URLhaus platform, identified by a hash (MD5/SHA256 hash). Please consider that not all payloads \nare malicious. For example, a URL may no longer be malicious and no longer serve malware.\n\n#### Recent vs Active vs Full Datasets\n\n- **Recent**: An export of URLs recently added to URLhaus within the past 30 days.\n- **Active**: An export of active (online) malware distribution sites.\n- **Full**: An export of URLs that are either actively distributing malware or that have been added to URLhaus \nwithin the past 90 days.\n\n### Authentication\n\nThis file export endpoint supports API Key authentication method. Requests are authenticated by\nAPI key via the `api_key` URL path parameter; this enables 3rd party tooling to download export files when\nauthentication schemes such as Bearer JWT are not natively supported.\n\nFor full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-).\n" operationId: urlhausExportDownloadWithAPIKey parameters: - description: API key for authentication. in: path name: api_key required: true schema: type: string - description: The name of the export file you want to download. in: path name: file_name required: true schema: enum: - full.csv.zip - full.json.zip - hostfile.txt - online.csv - online.json - payload.csv.zip - recent.csv - recent.json - rpz.txt - urlhaus_clamav.ndb - urlhaus_clamav.ndb.sha256 - urlhaus_ids.rules - urlhaus_ids.tar.gz - urlhaus_ids_suricata.rules - urlhaus_ids_suricata.tar.gz - urls_full.txt - urls_online.txt - urls_recent.txt example: recent.json type: string x-enum-descriptions: full.csv.zip: URLs that are either actively distributing malware or that have been added to URLhaus within the past 90 days, in CSV format, ZIP compressed. full.json.zip: URLs that are either actively distributing malware or that have been added to URLhaus within the past 90 days, in JSON format, ZIP compressed. hostfile.txt: Host file format dataset. online.csv: Active malware malware URLs in CSV format. online.json: Active malware malware URLs in JSON format. payload.csv.zip: Collected payloads in CSV format, ZIP compressed. recent.csv: Recent URL additions (last 30 days) in CSV format. recent.json: Recent URL additions (last 30 days) in JSON format. rpz.txt: DNS Response Policy Zone dataset. urlhaus_clamav.ndb: ClamAV signature database file. urlhaus_clamav.ndb.sha256: ClamAV SHA256 checksum file. urlhaus_ids.rules: URLhaus Snort/Suricata IDS Ruleset. urlhaus_ids.tar.gz: URLhaus Snort/Suricata IDS Ruleset compressed in tar.gz format. urlhaus_ids_suricata.rules: URLhaus Suricata-specific IDS Ruleset (using stick buffers). urlhaus_ids_suricata.tar.gz: URLhaus Suricata-specific IDS Ruleset (using stick buffers) compressed in tar.gz format. urls_full.txt: Full URL list in plain-text format. urls_online.txt: Active malware URL list in plain-text format. urls_recent.txt: Recent URL additions list (last 30 days) in plain-text format. responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Download Export File(s) tags: - URLhaus x-badges: - name: New position: before /urlhaus/v2/files/exports/misp/{api_key}/{file_name}: get: description: "Indicators of compromise (IOCs) from the URLhaus platform are available as MISP events. New MISP events are \ngenerated daily.\n\n### MISP File Types\n\n- Each `UUID.json` file contains the MISP data for a single event and all of its associated indicators.\n- `manifest.json` is a summary file which lists every event file included in the collection, allowing MISP \n instances to see what events are available without downloading every full event file.\n\n### Authentication\n\nThis file export endpoint supports API Key authentication method. Requests are authenticated by\nAPI key via the `api_key` URL path parameter; this enables 3rd party tooling to download export files when\nauthentication schemes such as Bearer JWT are not natively supported.\n\nFor full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-).\n" operationId: urlhausExportMispDownloadWithAPIKey parameters: - description: API key for authentication. in: path name: api_key required: true schema: type: string - description: The name of the MISP export file or manifest you want to download. examples: MISP export: value: 234eeb09-1141-4d32-92bf-57b8e22dbd09.json manifest: value: manifest.json in: path name: file_name required: true schema: type: string responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Download MISP Export File tags: - URLhaus x-badges: - name: New position: before /urlhaus/v2/files/samples/{api_key}/{sha256_hash}: get: description: | Identical to [Download Sample File](#tag/urlhaus/get/urlhaus/v1/files/samples/{sha256_hash}), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: urlhausSampleDownloadByHashWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: The SHA256 hash of the sample file you want to download. example: 4293c1d8574dc87c58360d6bac3daa182f64f7785c9d41da5e0741d2b1817fc7 in: path name: sha256_hash required: true schema: type: string responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Download Sample File (API key in URL) tags: - URLhaus x-badges: - name: New position: before /v1/login: post: description: "Important: This section is relevant only to endpoints available to query i.e., all endpoints other than those \nto “Export File”. \n\nUse this login endpoint to obtain a session JWT (JSON Web Token) which can be used to authenticate these \nabuse.ch API endpoints. You must provide your abuse.ch API account credentials (username, password, and realm) \nin the request body to obtain a valid JWT. The `realm` must be set to `abusech`, which is the only supported realm \nfor this platform.\n\nThe returned JWT is valid for 24 hours. The expiry timestamp is returned by the API in the `expires` field of \nthe response, and it is also available in the JWT claims itself. These expiry timestamps are in Unix epoch format \n(seconds since January 1, 1970). You can use these epochs to determine when the JWT will expire and when you need \nto re-authenticate to obtain a fresh and valid JWT. We recommend refreshing the token when the current one is close \nto expiration.\n\n> [!warning]\n> Please do *not* request a fresh JWT for each API request. This action is penalized to protect against brute-force \n> attacks and may result in API access being temporarily throttled or blocked.\n\nIn order to authenticate API requests (excluding this login endpoint), a valid JWT must be included in the \n`Authorization` header, prefixed with the word `Bearer`, e.g.\n\n```curl\n# curly braces are used to indicate where you should replace the values with your own - do not include them in the request\ncurl 'https://{{HOST}}/api/urlhaus/v1/urls' -H 'Authorization: Bearer {{YOUR_JWT_TOKEN}}'\n```\n" operationId: authLogin requestBody: content: application/json: schema: description: Log into the abuse.ch API to obtain a session JWT. The returned JWT is valid for 24 hours. properties: password: description: The password for the abuse.ch API account. example: password format: password type: string realm: description: Only the `abusech` realm is supported for the abuse.ch API platform. example: abusech type: string username: description: The email address associated with your abuse.ch API account. example: john.doe@example.com type: string required: - username - password - realm type: object description: The abuse.ch API login credentials. required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/AuthSession' description: The request was successful, and the server has returned a valid JWT. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: [] servers: [] summary: Login tags: - Authentication /yaraify/v1/files/samples/{sha256_hash}: get: description: "Download sample file by SHA256 hash. Note that files for which the reporter has chosen the no sharing option are not \navailable for download.\n\n- Files are zipped using AES128 encryption and protected with the password `infected` for security purposes. If \nyou receive an `unsupported compression type 99` error when trying to unzip, it is likely that your tool/library \ndoes not support AES encryption. Please switch to a different tool or library such as `7z` which does support it, \ne.g. `7z x -pinfected 9608954039df864624c7df090b3733abd2a67680ebef3b74bc4ecf429482f463`\n- The decompressed files will always have a `.bin` extension, regardless of their original file type. This is done\nto prevent accidental execution of potentially malicious files. You can find the original file type via the API.\n- We have a minimum 1 month retention period for files. If you attempt to request files older than that, you may\nreceive a `404 Not Found` response.\n" operationId: yaraifySampleDownloadByHash parameters: - description: The SHA256 hash of the sample file you want to download. example: f7f8694df632a541576229d89fa136e016f311fffd152b736ff6e330e553ec9a in: path name: sha256_hash required: true schema: type: string responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Download Sample File tags: - YARAify /yaraify/v1/metadata: get: description: "Returns a list of most recent file metadata records, or a filtered list of the search results if \none of the supported search query parameters is provided. Only **one** of the search query parameters can be \nprovided at a time, where providing multiple will result in a `400 Bad Request` response.\n\nSupported search query parameters (optional and mutually exclusive):\n- `yara_rule`\n- `imphash`\n- `tlsh`\n- `telfhash`\n- `gimphash`\n- `dhash_icon`\n\nPagination query parameters are also supported (but are optional), and can be used to limit the number of results returned.\n" operationId: yaraifyMetadataSearch parameters: - description: Search files matching the case-sensitive YARA rule name. Cannot be combined with the other search query parameters. examples: omitted: value: "" rule name: value: MALWARE_Win_Neshta in: query name: yara_rule required: false schema: type: string - description: The imphash you want to search for. Cannot be combined with the other search query parameters. examples: hash: value: 0035ece24c351f8bac8da9e8a2988620 omitted: value: "" in: query name: imphash required: false schema: type: string - description: The tlsh you want to search for. Cannot be combined with the other search query parameters. examples: hash: value: T10016DD42A3F94608F6F77F7469B916604E3BBCA6AD79C21C1284505E5EB2E40CDB0B73 omitted: value: "" in: query name: tlsh required: false schema: type: string - description: The telfhash you want to search for. Cannot be combined with the other search query parameters. examples: hash: value: t100115e18893812f087a24cdd2bedff76e49170db5a225e37ce10ed5a9a29a424d00c2c omitted: value: "" in: query name: telfhash required: false schema: type: string - description: The gimphash you want to search for. Cannot be combined with the other search query parameters. examples: hash: value: 207afdd0ad108c8f2417defdf57d9c355cacd646da60e988bfc1a020d5b2bf18 omitted: value: "" in: query name: gimphash required: false schema: type: string - description: The dhash icon you want to search for. Cannot be combined with the other search query parameters. examples: hash: value: 00928e8e8686b800 omitted: value: "" in: query name: dhash_icon required: false schema: type: string - description: The ClamAV signature you want to search for. Cannot be combined with the other search query parameters. examples: hash: value: Win.Dropper.Ajku-10014126-0 omitted: value: "" in: query name: clamav required: false schema: type: string - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/FileMetadataList' description: The list of file metadata search matches was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Search File Metadata tags: - YARAify /yaraify/v1/metadata/{hash}: get: description: | Query YARAify for file metadata by hash. Also returns relevant tasks. operationId: yaraifyMetadataGetByHash parameters: - description: The hash of the file to look up metadata for. This can be a SHA256, MD5, SHA3-384 or SHA1 hash. example: 780de51cf9fd0ef3850201f9a90103aff2ce625f70279be0ff6b9e7541ca75ba in: path name: hash required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/FileMetadata' description: The request was successful, and the server has returned the file details. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Get File Metadata by Hash tags: - YARAify /yaraify/v1/rules: get: description: "You can get a list of the most recent deployed YARA rules on YARAify as follow. Please take note that the author of \nthe YARA rule must have set the YARA rule's meta field `yarahub_rule_matching_tlp` to `TLP:WHITE`.\n" operationId: yaraifyRuleMetadataList parameters: - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/YaraRuleMetadataList' description: The request was successful, and the server has returned the YARA rules. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: List Most Recent Yara Rules Metadata tags: - YARAify /yaraify/v1/tasks: get: description: | Searches for tasks. operationId: yaraifyTasksSearch parameters: - description: The hash of the file to look up metadata for. This can be a SHA256, MD5, SHA3-384 or SHA1 hash. example: 780de51cf9fd0ef3850201f9a90103aff2ce625f70279be0ff6b9e7541ca75ba in: query name: hash required: false schema: type: string - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/TaskList' description: The request was successful, and the server has returned the task. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Search Tasks tags: - YARAify /yaraify/v1/tasks/{task_id}: get: description: "Fetches the current status of a Task ID. If the task has already been processed by the scanning engine, \nthis includes the scan results.\n" operationId: yaraifyTaskGet parameters: - description: The unique identifier (UUIDv1) of the task. example: 8d13946f-4b9f-11f0-9b97-42010aa4000b in: path name: task_id required: true schema: format: uuid type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/Task' description: The request was successful, and the server has returned the task. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' security: - BearerJwt: [] summary: Get Task by ID tags: - YARAify /yaraify/v2/{api_key}/metadata: get: description: | Identical to [Search File Metadata](#tag/yaraify/get/yaraify/v1/metadata), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: yaraifyMetadataSearchWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: Search files matching the case-sensitive YARA rule name. Cannot be combined with the other search query parameters. examples: omitted: value: "" rule name: value: MALWARE_Win_Neshta in: query name: yara_rule required: false schema: type: string - description: The imphash you want to search for. Cannot be combined with the other search query parameters. examples: hash: value: 0035ece24c351f8bac8da9e8a2988620 omitted: value: "" in: query name: imphash required: false schema: type: string - description: The tlsh you want to search for. Cannot be combined with the other search query parameters. examples: hash: value: T10016DD42A3F94608F6F77F7469B916604E3BBCA6AD79C21C1284505E5EB2E40CDB0B73 omitted: value: "" in: query name: tlsh required: false schema: type: string - description: The telfhash you want to search for. Cannot be combined with the other search query parameters. examples: hash: value: t100115e18893812f087a24cdd2bedff76e49170db5a225e37ce10ed5a9a29a424d00c2c omitted: value: "" in: query name: telfhash required: false schema: type: string - description: The gimphash you want to search for. Cannot be combined with the other search query parameters. examples: hash: value: 207afdd0ad108c8f2417defdf57d9c355cacd646da60e988bfc1a020d5b2bf18 omitted: value: "" in: query name: gimphash required: false schema: type: string - description: The dhash icon you want to search for. Cannot be combined with the other search query parameters. examples: hash: value: 00928e8e8686b800 omitted: value: "" in: query name: dhash_icon required: false schema: type: string - description: The ClamAV signature you want to search for. Cannot be combined with the other search query parameters. examples: hash: value: Win.Dropper.Ajku-10014126-0 omitted: value: "" in: query name: clamav required: false schema: type: string - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/FileMetadataList' description: The list of file metadata search matches was successfully returned. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Search File Metadata (API key in URL) tags: - YARAify x-badges: - name: New position: before /yaraify/v2/{api_key}/metadata/{hash}: get: description: | Identical to [Get File Metadata by Hash](#tag/yaraify/get/yaraify/v1/metadata/{hash}), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: yaraifyMetadataGetByHashWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: The hash of the file to look up metadata for. This can be a SHA256, MD5, SHA3-384 or SHA1 hash. example: 780de51cf9fd0ef3850201f9a90103aff2ce625f70279be0ff6b9e7541ca75ba in: path name: hash required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/FileMetadata' description: The request was successful, and the server has returned the file details. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Get File Metadata by Hash (API key in URL) tags: - YARAify x-badges: - name: New position: before /yaraify/v2/{api_key}/rules: get: description: | Identical to [List Most Recent Yara Rules Metadata](#tag/yaraify/get/yaraify/v1/rules), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: yaraifyRuleMetadataListWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - $ref: '#/components/parameters/QuerySince' - $ref: '#/components/parameters/QueryUntil' - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/YaraRuleMetadataList' description: The request was successful, and the server has returned the YARA rules. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: List Most Recent Yara Rules Metadata (API key in URL) tags: - YARAify x-badges: - name: New position: before /yaraify/v2/{api_key}/tasks: get: description: | Identical to [Search Tasks](#tag/yaraify/get/yaraify/v1/tasks), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response and query parameters. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: yaraifyTasksSearchWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: The hash of the file to look up metadata for. This can be a SHA256, MD5, SHA3-384 or SHA1 hash. example: 780de51cf9fd0ef3850201f9a90103aff2ce625f70279be0ff6b9e7541ca75ba in: query name: hash required: false schema: type: string - $ref: '#/components/parameters/QueryPaginationPageSize' - $ref: '#/components/parameters/QueryPaginationAfter' responses: "200": content: application/json: schema: $ref: '#/components/schemas/TaskList' description: The request was successful, and the server has returned the task. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Search Tasks (API key in URL) tags: - YARAify x-badges: - name: New position: before /yaraify/v2/{api_key}/tasks/{task_id}: get: description: | Identical to [Get Task by ID](#tag/yaraify/get/yaraify/v1/tasks/{task_id}), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers — for example Microsoft Defender XDR custom detection rules using KQL `externaldata`. See the v1 operation for the full description of the response. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: yaraifyTaskGetWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: The unique identifier (UUIDv1) of the task. example: 8d13946f-4b9f-11f0-9b97-42010aa4000b in: path name: task_id required: true schema: format: uuid type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/Task' description: The request was successful, and the server has returned the task. headers: Content-Type: schema: enum: - application/json type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Get Task by ID (API key in URL) tags: - YARAify x-badges: - name: New position: before /yaraify/v2/files/samples/{api_key}/{sha256_hash}: get: description: | Identical to [Download Sample File](#tag/yaraify/get/yaraify/v1/files/samples/{sha256_hash}), but authenticated by an API key supplied as a URL path segment instead of an `Authorization: Bearer` header. Use this variant when your tooling can only be configured with a URL and cannot set HTTP headers. For full details on authentication methods, see [Getting Started > Authentication](#section/Getting-Started/2.-Authenticate-with-the-API-). operationId: yaraifySampleDownloadByHashWithAPIKey parameters: - $ref: '#/components/parameters/ApiKeyPath' - description: The SHA256 hash of the sample file you want to download. example: f7f8694df632a541576229d89fa136e016f311fffd152b736ff6e330e553ec9a in: path name: sha256_hash required: true schema: type: string responses: "200": content: application/octet-stream: schema: format: binary type: string description: The request was successful, and the server has returned the file. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' summary: Download Sample File (API key in URL) tags: - YARAify x-badges: - name: New position: before security: [] servers: - description: Production URL url: https://api.spamhaus.com tags: - description: The abuse.ch API Authentication endpoints. name: Authentication - description: The URLhaus API endpoints. name: URLhaus x-displayName: Malware URLs (URLhaus) - description: The ThreatFox API endpoints. name: ThreatFox x-displayName: Malware IOCs (ThreatFox) - description: The MalwareBazaar API endpoints. name: MalwareBazaar x-displayName: Malware Samples (Malware Bazaar) - description: The YARAify API endpoints. name: YARAify x-displayName: YARA Scan Results (YARAify)