IOC Finder¶

PyPI - Downloads

Welcome to the documentation for the ioc-finder library - a library to find different types of indicators of compromise (a.k.a observables) and data pertinent to indicators of compromise!

📢 Announcement: I'm looking for sponsorship for this project. I have a number of improvements and helpful features I'd like to add, but need some support to continue working on this project. If you use this project for work and/or find it useful, please consider contributing even a small amount. Thanks!

Quick-Start¶

Install ioc-finder:

pip install ioc-finder

Use it:

from ioc_finder import find_iocs

text = ""

iocs = find_iocs(text)
iocs['domains']
iocs['urls']

Overview (INTERACTIVE!)¶

Enter some text with IOCs here and click "Parse IOCs" to see how ioc-finder parses IOCs. Click "Reload"

The code above uses Pyodide to provide a Python3.9 runtime in the browser using WebAssembly. Enjoy!

Capabilities¶

Data types found by ioc-finder

Autonomous System Numbers (ASNs) (in multiple formats such as asn1234 and as 1234)
Bitcoin addresses (P2PKH, P2SH, and Bech32)
CIDR ranges (currently ipv4 ranges; ipv6 ranges coming soon)
CVEs (e.g. CVE-2014-1234)
Domain names (support for Unicode domain names (e.g. ȩxample.com) is coming soon)
Email addresses (both standard format (e.g. [email protected]) and an email with an IP address as the domain (e.g. test@[192.168.0.1]))
File hashes (md5, sha1, sha256, sha512, and import hashes, and authentihashes)
File paths (beta)
Google Adsense Publisher IDs
Google Analytics Tracker IDs
IP address (IPv4 and IPv6)
MAC addresses (beta)
Monero (crypto-currency) addresses
Registry key paths (e.g. "HKEY_LOCAL_MACHINE\Software\Microsoft\Windows)
SSDeep hashes (beta)
URLs (URLs with and without schemes)
User agents (beta)
XMPP addresses (basically, this captures email addresses whose domain names contain "jabber" or "xmpp")
MITRE ATT&CK data (see more info)*:
- Pre-attack tactics and techniques (and sub-techniques)
- Enterprise mitigations, tactics, and techniques (and sub-techniques)
- Mobile mitigations, tactics, and techniques (and sub-techniques)
TLP labels

Have another data-type you would like ioc-finder to parse? Raise an issue and we'll see what we can do!

Configuration Options

This library also provides options to:

Parse domain name from a URL
Parse domain name from an email address
Parse IP address from a CIDR range
Parse URLs without a scheme (e.g. without https://)
Parse import hashes and authentihashes

Known Limitations

When parsing registry key paths, this library will NOT properly parse a registry key path where the last section contains a space. For example, <HKCU>\software\microsoft\windows\currentversion\explorer\advanced on will be parsed as <HKCU>\software\microsoft\windows\currentversion\explorer\advanced (the space in the final section is removed).
The items listed above (in the "Capabilities" section) that are postceded by "(beta)" are not very robust and may still have major issues. Any feedback or issues related to these items are much appreciated.
When parsing markdown, if there is a domain name that is surrounded by underscores (which would make the domain name italic in some flavours of markdown - e.g. _google.com_), the domain will be parsed including the leading underscore (e.g. _google.com_ would be parsed as _google.com).

Feedback¶

If you have any ideas to improve this package, please raise an issue!

Other Helpful Projects¶

You may also be interested in https://github.com/ioc-fang/ioc_fanger, a project to fang and defang indicators of compromise. For example,

defanging:

example.com => example[.]com
https://example.com => hXXps://example[.]com

and fanging:

example[.]com => example.com
example(.)com => example.com
me AT example(.)com => [email protected]

Credits¶

This project uses the ioc_fanger package to make sure that all indicators in the text are properly fanged.

This package was created with Cookiecutter and Floyd Hightower's python-project-template project template.