Skip to main content

Panthera(P.)uncia

Official CLI utility for Subdomain Center & Exploit Observer

Downloads GitHub stars

Puncia is the official command-line client for two A.R.P. Syndicate intelligence APIs — point it at a domain, a brand, or a vulnerability ID and get structured JSON back in seconds, no browser required:

  • 🕸️ Subdomain Center — subdomain enumeration, subdomain takeover surfacing, shadow IT discovery, and brand impersonation / lookalike-domain (typosquat) detection at internet scale.
  • 💥 Exploit Observer — exploit & vulnerability intelligence across 150+ identifier schemes (CVE, GHSA, EDB, MSF, ZDI, nation-state feeds and more), with EPSS + VEDAS maturity scoring on every lookup and SBOM scanning.
$ puncia subdomain arpsyndicate.io
╭──────────────────────────────────────────────────────────────────────╮
│ Panthera(P.)uncia v0.42                                              │
│ subdomain recon · brand impersonation · exploit intel · sbom analysis│
│ A.R.P. Syndicate — https://www.arpsyndicate.io                       │
╰──────────────────────────────────────────────────────────────────────╯
[
  "advisories.arpsyndicate.io",
  "asm.arpsyndicate.io",
  "blog.arpsyndicate.io",
  ...
]

$ puncia sbom bom.json ./out
puncia ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% (128/128) 0:00:41

Please note that although these results can sometimes be pretty inaccurate & unreliable, they can greatly differ from time to time due to their self-improvement capabilities.

Aggressive rate-limits can be avoided with an API key: https://www.arpsyndicate.io/pricing.html

Practical Applications

  1. Brand Impersonation & Phishing Domain Detection
    Surface replica, lookalike, and typosquat domains riding on your brand before they're used against you or your customers.
  2. Shadow IT & External Attack Surface Discovery
    Identify and monitor exposed subdomains and infrastructure spun up outside official channels.
  3. Subdomain Takeover Reconnaissance
    Enumerate the full subdomain footprint of a target, a key first step in spotting dangling/takeover-prone records.
  4. Advanced Vulnerability Research & Monitoring
    Discover and track known and emerging threats, including obscure or unlisted vulnerabilities.
  5. Scored CVE/GHSA Intelligence
    Every lookup carries EPSS + VEDAS maturity scores and CVSS, so known vulnerabilities can be prioritized in context.
  6. Vulnerability Detection in Software Bill of Materials (SBOM)
    Analyze software components for known exploits and security issues using structured SBOM data.
  7. Seamless Integration with CI/CD & Threat Intel Workflows
    Automate intelligence gathering and vulnerability checks within development or security pipelines.
  8. Monitoring Nation-State Exploit Trends
    Stay ahead of threats by tracking vulnerabilities flagged by foreign actors but not yet recognized by mainstream databases.
  9. Keyword-Based Subdomain Discovery
    Surface hosts carrying a given keyword across the internet, independent of a specific parent domain.
  10. Bulk Threat Intelligence Processing
    Run batch queries (domains, vulnerabilities, etc.) for scalable analysis across large datasets or enterprise asset inventories.
  11. Passive Reconnaissance for Red Teams
    Conduct stealthy reconnaissance by using passive data sources (no direct interaction with targets).
  12. Open Source Intelligence (OSINT) Collection
    Combine subdomain and exploit intelligence to enhance OSINT investigations.
  13. Compliance & Risk Management Support
    Enrich vulnerability data to support compliance audits (e.g., ISO 27001, SOC 2) with deeper context.

Installation

  1. From PyPi - pip3 install puncia
  2. From Source - pip3 install .

30-second Quickstart

pip3 install puncia

# subdomain footprint of a target (shadow IT / attack surface / takeover recon)
puncia subdomain example.com

# lookalike / typosquat / brand-impersonation domains
puncia replica example.com

# what's known about a CVE
puncia exploit CVE-2021-44228

Usage

puncia <mode> <query> [output] [--match M] [--domain D] [--limit N] [--offset N]
                               [--crawl] [--filter KEY=VALUE] [--format json|csv]
                               [--api-key K] [--concurrency N]
                               [--timeout S] [--retries N] [--quiet]

Run puncia --help for the full reference. Results are printed to stdout; the banner, progress bars, warnings and errors all go to stderr, so puncia subdomain example.com > out.json always yields clean, valid JSON.

Exit codes: 0 success · 1 request or input error · 2 usage error.

  1. (PAID) Store an API key (storekey) - puncia storekey <api-key>

    • Stored at ~/.puncia with 0600 permissions. $PUNCIA_API_KEY overrides it, which is usually what you want in CI.
  2. (FREEMIUM) Query Domains, clustered by domain (subdomain / cuttlefish engine) - puncia subdomain <domain> <output-file>

    • Pagination (authenticated only): an authenticated result has no total cap. By default subdomain/replica/keyword walk every page and merge them for you, de-duplicating across pages; --limit (1–1,000,000) sets the page size, otherwise the API's default of 200,000 is used explicitly on every page. Pass --offset to fetch exactly one raw page yourself instead, e.g. for a resumable or streaming walk:
      puncia subdomain bigco.com --limit 50000 --offset 0
      # stderr prints: note: more results available — continue with --offset 50000 --limit 50000
      puncia subdomain bigco.com --limit 50000 --offset 50000
      
      The hint advances by the rows the page actually returned, so consecutive manual pages may overlap by a few rows — de-duplicate when you concatenate them. Anonymous requests ignore --limit/--offset server-side (always a shuffled sample of up to 500 rows); puncia warns rather than pretending they did something.
    • Live crawl (authenticated only): --crawl supplements stored results with a live discovery pass. A given domain is only actually re-crawled once every ~6h — requests inside that window get the cached crawl result instantly. Puncia reports the outcome on stderr: crawl: fresh, 12 newly discovered name(s) (also partial / running / cooldown / disabled). On partial/running part of the crawl is still going server-side; re-run with --crawl in a minute for the rest.
      puncia subdomain bigco.com --crawl
      
  3. (FREEMIUM) Query Replica Domains, clustered by brand (replica / octopus engine) - puncia replica <domain> --match <prefix|exact|substring> <output-file>

  4. (FREEMIUM) Query by Keyword, clustered by keyword (keyword / ammonites engine) - puncia keyword <keyword> --match <exact|prefix> <output-file>

    • Optionally scope the keyword to a single domain with --domain: puncia keyword blog --domain bandcamp.com
  5. Query Exploit & Vulnerability Identifiers (exploit)

    • (FREE) Watchlist (^WATCHLIST_IDES) — CVEs trending in the latest crawl plus CVEs that became exploitable for the first time in it; rebuilt every crawl - puncia exploit ^WATCHLIST_IDES <output-file>
    • (FREE) Vulnerability & Exploit Identifers Watchlist with Descriptions (^WATCHLIST_INFO) - puncia exploit ^WATCHLIST_INFO <output-file>
    • (FREE) Vulnerable Technologies Watchlist (^WATCHLIST_TECH) - puncia exploit ^WATCHLIST_TECH <output-file>
    • (FREE) Aggregate vulnerability/exploit stats (^STATS) - puncia exploit ^STATS <output-file>
    • (FREE) Service health (^HEALTH) - puncia exploit ^HEALTH <output-file>
    • (FREEMIUM) Supported Vulnerability Identifiers - puncia exploit <eoidentifier> --match <substring|prefix|exact> <output-file>
    • Metasploit modules come back as their Rapid7 module page (ruby bucket). A CVE id with a public PoC but no published CVE record yet (a reserved id the PoC author published first) is returned with a description starting ** UNPUBLISHED ** that summarises the evidence.
  6. (PAID) Non-CVE Identifiers by VEDAS group (noncve) - puncia noncve <browser/china/russia/europe/exploitable> <output-file>

  7. (PAID) Nuclei Template Candidates (nuclei) - puncia nuclei candidates <output-file>

    • CVEs that have a VEDAS id and no nuclei template yet but look templatable, highest priority first (priority = feasibility × impact). Each row carries a suggested template shape (protocol, method — active, oast, version, fingerprint-first — whether it needs auth, whether it is likely reachable over HTTP, its surface, whether it is a read or a state change, and the XSS kind), the package ecosystem, PoC sources, portable afrog/xray/jaeles/goby templates, test environments, existing templates for the same product, and the reasons behind the score.
    • Every page is fetched and merged automatically; --limit sets the page size (max 1000) and --offset fetches exactly one page instead (stderr then says how far through the ranking you are and how to continue).
    • Narrow with repeatable --filter KEY=VALUE: min_feasibility, vendor, product, platform, cwe, method, protocol, kev, poc, portable.
    • CSV export: --format csv, or just give an output path ending in .csv — one row per CVE with the shape object flattened into its own columns (protocol, method, authenticated, likely_http, surface, state_change, xss_kind), list fields joined with ; (reasons with |), and cells that a spreadsheet would treat as a formula made inert.
      puncia nuclei candidates candidates.csv
      puncia nuclei candidates wp.csv --filter platform=wordpress --filter poc=true
      puncia nuclei candidates --filter kev=true --filter min_feasibility=0.5 --format csv > kev.csv
      
  8. (FREE) Subdomain Center service health (^HEALTH) - puncia subdomain ^HEALTH <output-file>

  9. Multiple Queries (bulk/sbom)

    • (FREEMIUM) Bulk Input JSON File Format - puncia bulk <json-file> <output-directory>
      {
          "subdomain": [
              "domainA.com",
              "domainB.com"
          ],
          "replica": [
              "domainA.com",
              "domainB.com"
          ],
          "keyword": [
              "keywordA",
              "keywordB"
          ],
          "exploit": [
              "eoidentifierA",
              "eoidentifierB"
          ]
      }
      
    • (FREEMIUM) SBOM Input JSON File Format - puncia sbom <json-file> <output-directory>

    Bulk and SBOM runs de-duplicate queries, cap parallelism at --concurrency (default 10), and — when no API key is present — pace requests to stay inside the free-tier budget automatically. Each result lands at <output-directory>/<mode>/<query>.json; a query that is not usable as a filename as-is (path separators, control characters, a Windows device name, over 200 characters, or a case-variant of another query) is scrubbed and gets a short ~<hash> suffix so two queries can never share one file. A run that finds no valid query at all exits 1; one with failed queries also exits 1 after writing every other result and listing the failures on stderr.

  10. (FREEMIUM) External Import

import asyncio
import puncia

async def main():
   # Without an API key (ratelimited)
   print(await puncia.query_api("exploit", "CVE-2021-3450"))
   print(await puncia.query_api("subdomain", "arpsyndicate.io"))

   # With an API key
   await puncia.store_key("ARPS-xxxxxxxxxx")
   api_key = await puncia.read_key()
   print(await puncia.query_api("subdomain", "arpsyndicate.io", apikey=api_key))
   print(await puncia.query_api("replica", "arpsyndicate.io", match="exact", apikey=api_key))
   print(await puncia.query_api("noncve", "exploitable", apikey=api_key))

   # Nuclei template candidates: filtered, every page merged, saved as CSV
   candidates = await puncia.query_api(
       "nuclei", "candidates", "candidates.csv", apikey=api_key,
       filters={"platform": "wordpress", "poc": "true"}, output_format="csv",
   )
   print(puncia.candidates_to_csv(candidates))  # or render CSV yourself

   # Static endpoints (unauthenticated, unlimited)
   print(await puncia.query_api("subdomain", "^HEALTH"))
   print(await puncia.query_api("exploit", "^STATS"))

   # Live crawl, with the outcome surfaced via a callback
   await puncia.query_api(
       "subdomain", "bigco.com", apikey=api_key, crawl=True,
       on_crawl=lambda h: print("crawl status:", h.get("X-Crawl-Status")),
   )

   # Write straight to disk
   await puncia.query_api("subdomain", "arpsyndicate.io", "out.json", apikey=api_key)

asyncio.run(main())

Failures raise puncia.PunciaError; an empty result ({} / []) is returned as-is rather than being treated as an error. Anonymous calls share one process-wide free-tier limiter per API, so a loop over query_api is paced correctly without any extra plumbing; reuse one session across many queries by passing session= (the timeout= still applies per request), and pass your own limiter= only if you need different pacing, exactly as process_bulk() does.

from puncia import PunciaError, query_api

try:
    data = await query_api("exploit", "CVE-2021-3450", apikey=api_key)
except PunciaError as exc:
    print(f"lookup failed: {exc}")

Development

git clone https://github.com/ARPSyndicate/puncia && cd puncia
pip install --upgrade pip     # editable installs need pip >= 21.3
pip install -e ".[dev]"
pytest                        # 154 offline tests, no API calls or network access

The test suite is fully offline — it covers URL construction, output-path containment, SBOM parsing, bulk planning, page walking, CLI hints and ratelimiter timing without touching the network, so it is safe to run in any environment.

Noteworthy Mentions

Metadata

Release files for puncia 0.42

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for puncia 0.42
File Size Uploaded Provenance Actions
puncia-0.42.tar.gz 48.1 kB Without provenance Details for puncia-0.42.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for puncia 0.42
File Interpreter ABI Platform Actions
puncia-0.42-py3-none-any.whl Python 3 none any Details for puncia-0.42-py3-none-any.whl

Total release size: 76.4 kB

Release files / puncia-0.42.tar.gz

Download URL puncia-0.42.tar.gz
Size 48.1 kB
Tags Source
SHA-256 checksum
How to use checksums
113b1d3fda7878511afe196577de1e5ef14e68574771e726339b0e9242229118
BLAKE2b-256 checksum
How to use checksums
4c0a346669487c541e8771b6457f598ca3abb9c8620dfa216a5e083bd7d858ec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.15

Release files / puncia-0.42-py3-none-any.whl

Download URL puncia-0.42-py3-none-any.whl
Size 28.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a6faeb1f4a0dd61baa6082be7b3a4f0584c160c820e8a9ba09f077743e3ed6b8
BLAKE2b-256 checksum
How to use checksums
2bca3bfd8834992b2cc640ad550311e9199c03ff516ad2b76bbc7e0e3a0a12f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.15

Security for puncia 0.42

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.42 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page