ioc-finder is a modular Python library that parses observables such as URLs, IP addresses, and email addresses out of raw text, built primarily for defenders doing threat-intelligence work.

ioc-finder, hosted at fhightower/ioc-finder on GitHub, is a Python package whose single purpose is extracting indicators of compromise — the community also calls them observables or network data — from arbitrary text. Where most IOC tooling assumes structured input like STIX bundles or CSV feeds, this library targets the messier reality of the analyst workflow: prose-heavy threat reports, pasted malware configuration dumps, ticket comments, and sandbox output. It ships on PyPI as ioc_finder, is licensed under LGPL-3.0, and carries roughly 184 stars with continuous integration, linting, and codecov badges visible in the README, all signals of a maintained, tested project rather than a weekend script.

The README is short, but the repo's topic list does the heavy lifting in describing intent. Tags like threat-intelligence, threat-hunting, malware-analysis, malware-research, and threat-sharing position this squarely as a defensive-side utility for people who process large volumes of security text daily. Other topics — grammar-parser, grammars, cidr-range, ipv4, parse-urls, observable — hint at the implementation approach: rather than an unreadable pile of regular expressions, the project appears to define grammars for each observable type and parse text against them. That design choice, advertised by the maintainer's own tagging, is what makes the package both modular and extensible.

The word "modular" in the project's self-description matters operationally. In practice it means each observable type — URLs, IPv4 addresses, CIDR ranges, email addresses, and presumably the usual supporting casts like hostnames — is handled by its own grammar, so adding or refining a parser for one indicator class doesn't destabilize the others. For a blue-team engineer wiring this into a threat-intel ingestion pipeline, that modularity translates into predictable behavior: when a new indicator format emerges, you patch one grammar instead of untangling a monolithic regex blob. It also makes the library's unit-testable surface, evidenced by the codecov badge, genuinely meaningful per-observable-type.

Installation is the standard pip path for a PyPI-published package. A minimal example of integration looks like importing the package and passing text through its finder function — the canonical pattern being from ioc_finder import find_iocs followed by feeding it a string, with results returned as a structured dictionary keyed by observable type. That dictionary shape is what makes the library composable: you can hand the output directly to enrichment stages, feed CIDR blocks into firewall rule generation for allow/deny review, or queue extracted URLs for detonation-free reputation lookups in downstream tooling.

What elevates ioc-finder above a homemade regex scraper is precision in the corners. Any analyst who has tried to pull IPv4 addresses out of prose knows the failure modes: version numbers mistaken for IPs, timestamps mangled into CIDR-like strings, and URLs truncated at punctuation. A grammar-based approach, combined with the project's visible test coverage, suggests these edge cases are handled deliberately rather than accidentally. The topic tags cidr-range and cidr-ranges as distinct entries indicate range parsing is a first-class feature, not an afterthought — useful when reports describe attacker infrastructure as network blocks rather than individual hosts.

The maintainer also maintains an interactive documentation site linked from the README, described enthusiastically as "it's interactive!", plus a live demo. For a parsing library, an interactive playground is a genuinely useful artifact: you can paste sample text and immediately see which observables the current release extracts, which is the fastest way to evaluate fitness for a given feed format before writing any integration code. Documentation hosted separately from the README, with its own demo, signals the maintainer treats onboarding seriously — a meaningful differentiator in the threat-intel tooling space where many utilities are README-only.

There is an honest signal worth noting for procurement-minded readers: the README includes an explicit sponsorship appeal. The maintainer states plainly that there are improvements and features he would like to add and asks commercial users to contribute financially. This is neither a red flag nor marketing fluff — it's a transparent sustainability model, and it also tells you the roadmap exists but is resource-constrained. Organizations building ioc-finder into production threat-intelligence pipelines should factor that in, either by sponsoring or by being prepared to contribute grammars upstream under the LGPL-3.0 terms.

The LGPL-3.0 license deserves a sentence of analysis for team leads. Because it is a library consumed via pip rather than a standalone binary, most commercial usage patterns — importing it in your internal tooling — are unproblematic, with the copyleft obligations attaching to modifications of the library itself. For a SOC or threat-intel platform vendor evaluating dependencies, that's a comfortable middle ground between permissive and full GPL, and it's consistent with the maintainer's sponsorship-based funding model.

In an authorized workflow, where this tool fits is squarely on the defensive side of the house. A typical chain looks like this: an analyst receives a vendor threat report or pulls narrative output from a malware-analysis sandbox; ioc-finder converts that narrative into a machine-readable set of URLs, IPs, CIDR ranges, and email addresses; those observables then flow into a TIP (threat intelligence platform), SIEM watchlists, or hunting queries. The library itself performs no network operations, no scanning, and no retrieval — it is a pure text-to-structure transformer, which makes it one of the least risky dependencies you can add to a security pipeline from a policy standpoint.

The hacktoberfest topic tag is a small but real indicator of community posture — it signals the maintainer opens the repo to first-time contributors during community events, which historically correlates with a friendlier contribution process and fresher test suites. Combined with visible CI workflows for both testing and linting, the project presents as a well-groomed open-source citizen. For defenders, that matters less as a warm feeling and more as operational reliability: parsing libraries that silently regress are pipeline poison, and badge-verified CI plus coverage tracking is the mitigating control.

Compared with alternatives, ioc-finder occupies the niche of a focused, library-shaped tool rather than a framework. You wouldn't use it to manage feeds (that's TIP territory) or to detonate samples (that's sandbox territory); you use it precisely at the moment unstructured text needs to become structured observables. Its narrow scope, grammar-driven architecture, interactive docs, and permissive-for-libraries licensing make it a low-friction choice for that single responsibility — and for authorized teams processing their own threat data, it's a quiet workhorse that removes one of the most tedious manual steps in threat-intelligence operations.

Educational analysis for authorized security professionals. Use only in controlled, authorized environments.

Related coverage

• karton for distributed malware analysis pipelines


• spyre for fast YARA-based IOC scanning across endpoints during incident response


• lenspect for accessible malware triage on the Linux desktop