io.github.Jam0k/threatcluster

Credits and rate-limit state from the headers of the most recent API responses in this session, plus what has been spent so far. No API call is made and nothing is charged; call it to pace yourself before a burst of lookups. Free keys: 100 credits a day, 30 requests a minute, budget refills at 00:00 UTC.

CVEs published or updated in a window, filtered to the ones that matter: in CISA KEV (`kev_only`), with a public exploit (`has_exploit`), by severity, vendor or product. Use for 'what should we patch this week' and 'is anything in our stack being exploited'. 1 credit.

Full record for one cluster returned by another tool: summary, timeline, the underlying articles with their source URLs, extracted entities and CVEs. Call this for the 1-3 clusters that matter before answering in depth. `identifier` is the cluster id, its 8-character short id, or the slug from a threatcluster.io/cluster/... URL. Set `include_iocs` to also fetch the cluster's validated indicators (+1 credit). 1 credit (2 with IOCs).

One CVE record: description, CVSS, EPSS score and percentile, CISA KEV status with due date, known ransomware use, public exploit count and links, affected vendors and products, references. 1 credit.

Ransomware leak-site victim listings: who a group claims to have hit, when, sector, country. These are claims by the groups, not confirmed breaches. Returns the newest listings matching the filters plus a tally of every listing in the window by group, sector and country, so 'most active group' and 'most hit sector' questions are answered from the tally, not the sample. Use for any question about ransomware victims, a group's activity, or a sector / country being hit. 2 credits (listings + tally).

Profile of a threat actor, malware family, tool, company, product, country, industry or CVE as tracked in the corpus: how often it appears, first and last seen, the recent clusters and articles it appears in, and the entities it co-occurs with. Give `entity_type` when the name is ambiguous (a company that is also a malware name). 2 credits (name resolution + profile).

The newest incident clusters in a window, no keyword. Use for 'what happened today / this week', 'what's new', 'what should a SOC know'. `sort_by=new` lists by first report time; `sort_by=trending` ranks by how fast coverage is growing. 1 credit.

One call across the whole corpus: incident clusters, entity profiles (actors, malware, vendors, CVEs) and dark-web ransomware listings that match the query. Costs 5 credits for the phrase; if that returns little it retries one call per word (up to 4 more, so 25 at worst) and `matched_stage` says which stage the results came from. Prefer search_threats (1 credit per term) when you only need clusters; use this when you do not know whether the name is an actor, a victim or a product, or when you want the dark-web hits too.

Keyword search over incident clusters (each cluster is one deduplicated story built from every source that covered it). Best for named things: actors, malware, vendors, products, CVE ids, companies, countries. Matching is literal: it tries the exact phrase, then all words together, then any word, and finally widens the time window if still under 3 hits; `matched_stage` says which stage matched. Use `alternatives` for spellings and synonyms (UK / United Kingdom / British). Costs 1 credit per term searched; at most 8 API calls per invocation, and `api_calls` in the result says how many were made. For one call that also covers entity profiles and the dark web use search_everything instead (5 credits).

Which threat actors, ransomware crews, malware families, tools, vendors, products, CVEs, countries and industries are rising in the corpus over a window, with mention counts and the change against the previous window. Indicator types (hashes, IPs, wallets) are left out unless named in `entity_types`. 1 credit.