<img alt="Pius - Open-source attack surface discovery and OSINT reconnaissance tool for enumerating domains, subdomains, and IP ranges" src="docs/banner.webp" />

Pius - Attack Surface Discovery & OSINT Reconnaissance Tool

Discover domains, subdomains, and IP ranges (CIDRs) owned by any organization using certificate transparency, RIR registries, passive DNS, and 24 extensible plugins.

Pius is an open-source attack surface discovery tool written in Go. Given a company name, it maps the complete external attack surface: domains, subdomains, and IP ranges (CIDRs). Pius queries certificate transparency logs, all five regional Internet registries (ARIN, RIPE, APNIC, AFRINIC, LACNIC), passive DNS databases, WHOIS/RDAP, BGP tables, and more through 24 discovery plugins.

Built for penetration testers, bug bounty hunters, and security teams who need reliable, repeatable asset discovery. Unlike ad-hoc reconnaissance scripts, Pius is production-grade: concurrent plugin execution, a three-phase discovery pipeline, multi-tier caching, confidence scoring for ambiguous results, graceful degradation, and passive-first OSINT defaults.

Table of Contents

• Why Pius: How It Compares to Amass and Subfinder
• Features
• Quick Start
• Plugins
  • Domain Plugins
  • CIDR Plugins
• How It Works: Three-Phase Discovery Pipeline
• Architecture
• Usage
  • Basic Discovery
  • CIDR Discovery
  • Output Formats
  • Plugin Selection
• Configuration
• FAQ
• Troubleshooting
• Contributing
• Security
• License

Why Pius: How It Compares to Amass and Subfinder

Pius fills the gap between subdomain enumeration tools (like subfinder) and full attack surface management platforms. If you need both domain and CIDR discovery from a single tool with confidence scoring and a phased pipeline, Pius is purpose-built for that workflow.

| Feature | Pius | amass | subfinder | |---------|------|-------|-----------| | Language | Go | Go | Go | | Single binary | Yes | Yes | Yes | | RIR CIDR discovery | Yes (all 5 RIRs) | Partial | No | | Phase pipeline | Yes (handle → CIDR) | No | No | | Confidence scoring | Yes | No | No | | Passive mode default | Yes | Yes | Yes | | Cache layer | Yes (24h) | No | No |

Features

Use Cases

• Penetration testing. Map an organization's external attack surface before an engagement.
• Bug bounty reconnaissance. Discover in-scope domains and IP ranges from an organization name.
• Attack surface management. Continuously monitor for new assets with passive-first defaults.
• Red team operations. Identify subsidiary and affiliated infrastructure through corporate registries (GLEIF, SEC EDGAR, Wikidata).

Capabilities

| Feature | Description | |---------|-------------| | 24 Discovery Plugins | 15 domain plugins + 9 CIDR plugins covering certificate transparency, passive DNS, WHOIS, RDAP, RPSL, BGP tables, favicon hashing, and subdomain permutation | | All 5 RIRs | ARIN (North America), RIPE (Europe/Middle East), APNIC (Asia-Pacific), AFRINIC (Africa), LACNIC (Latin America) | | Three-Phase Pipeline | Phase 0 runs independently, Phase 1 discovers RIR org handles, Phase 2 resolves handles to CIDRs; late-stage plugins enrich results using discovered assets | | Confidence Scoring | Ambiguous name-to-asset mappings are scored and flagged for review rather than silently dropped | | Multi-Tier Cache | API responses cached 24h as JSON; RPSL databases cached 24h as decompressed local files | | Passive Mode Default | Only OSINT sources queried by default; active plugins (DNS brute-force, zone transfer) opt-in | | Flexible Output | Terminal table, JSON array, and NDJSON (newline-delimited) formats | | Single Binary | Go-based tool compiles to one portable executable with no runtime dependencies |

Quick Start

Installation

Requires Go 1.25.0 or later.

go install github.com/praetorian-inc/pius/cmd/pius@latest

Or build from source:

git clone https://github.com/praetorian-inc/pius.git
cd pius
go build -o pius ./cmd/pius

Basic Usage

# Discover domains and CIDRs for an organization (passive mode)
pius run --org "Acme Corp"

# Add a domain hint to unlock more plugins
pius run --org "Acme Corp" --domain acme.com

# Include active plugins (DNS brute-force, zone transfer)
pius run --org "Acme Corp" --domain acme.com --mode all

Example Output

[domain] acme.com (crt-sh)
[domain] api.acme.com (crt-sh)
[domain] staging.acme.com (passive-dns)
[domain] acme.com (reverse-whois) ⚠ needs-review [confidence:0.42]
[cidr] 203.0.113.0/24 (arin)
[cidr] 198.51.100.0/22 (ripe)

List Available Plugins

pius list

Plugins

Domain Plugins

All domain plugins run in Phase 0 (independent, concurrent). They emit discovered domain names.

| Plugin | Data Source | Auth Required | Mode | Notes | |--------|-------------|---------------|------|-------| | crt-sh | Certificate Transparency logs | None | Passive | Deduplicates wildcard entries | | apollo | Apollo.io enrichment API | APOLLO_API_KEY | Passive | Caches results 24h; 0.85 confidence for domain queries | | github-org | GitHub organization search | GITHUB_TOKEN (optional) | Passive | Confidence-scored; 0.65 threshold to emit | | gleif | GLEIF LEI corporate registry | None | Passive | Discovers parent/subsidiary domains | | passive-dns | SecurityTrails passive DNS | SECURITYTRAILS_API_KEY | Passive | Historical subdomain records | | reverse-whois | ViewDNS reverse WHOIS | VIEWDNS_API_KEY | Passive | 0.75 confidence; registrant email matching | | dns-brute | Local DNS resolver | None | Active | 50 concurrent goroutines; embedded wordlist | | dns-zone-transfer | DNS AXFR | None | Active | Extracts A, AAAA, CNAME, MX, SRV records | | doh-enum | DNS-over-HTTPS resolvers | AWS credentials (optional) | Active | 50 concurrent workers; round-robin endpoint rotation; optional API Gateway deployment for IP diversity | | favicon-hash | Shodan + FOFA favicon search | SHODAN_API_KEY, FOFA_API_KEY (optional) | Active | MurmurHash3 of favicon; discovers origin IPs behind CDNs | | dns-permutation | Discovered subdomains (Phase 0) | None | Active | Phase 3; altdns-style permutations; wildcard filtering | | google-dorks | Google Knowledge Graph | None | Passive | Carousel scraping for subsidiary companies | | reverse-ip | PTR records, HackerTarget, ViewDNS | VIEWDNS_API_KEY (optional) | Passive | Phase 3; consumes CIDRs from Phase 2 | | wikidata | Wikidata SPARQL | None | Passive | P749/P355/P127 corporate relationships; 24h cache | | censys-org | Censys Platform API v3 | CENSYS_API_TOKEN, CENSYS_ORG_ID | Active | Searches host/cert data by org; emits domains + CIDRs; requires Starter+ plan; caches 24h |

CIDR Plugins

CIDR discovery uses a multi-phase pipeline: Phase 0 discovers CIDRs directly, Phase 1 discovers RIR organization handles, and Phase 2 resolves handles to CIDR blocks.

| Plugin | Phase | Data Source | Protocol | RIR Coverage | |--------|-------|-------------|----------|--------------| | asn-bgp | 0 (independent) | RIPE RIS BGP tables | HTTP REST | Global (announced prefixes) | | shodan | 0 (independent) | Shodan net: search | HTTP REST | Global (requires SHODAN_API_KEY) | | whois | 1 (handle discovery) | All 5 RIRs | HTTP REST | ARIN, RIPE, APNIC, AFRINIC, LACNIC | | edgar | 1 (handle discovery) | SEC EDGAR filings | HTTP REST | Global public companies | | arin | 2 (resolution) | ARIN RDAP | RDAP (RFC 7483) | North America | | ripe | 2 (resolution) | RIPE RDAP | RDAP (RFC 7483) | Europe, Middle East, Central Asia | | lacnic | 2 (resolution) | LACNIC RDAP | RDAP (RFC 7483) | Latin America & Caribbean | | apnic | 2 (resolution) | APNIC RPSL database | Cached gzip file | Asia-Pacific | | afrinic | 2 (resolution) | AFRINIC RPSL database | Cached gzip file | Africa |

How It Works: Three-Phase Discovery Pipeline

Pius uses a three-phase concurrent pipeline to discover organizational assets:

pius run --org "Acme Corp" --domain acme.com
              │
              ▼
       Plugin Registry
    (init() auto-registration)
              │
   ┌──────────┴─────────────────────────────┐
   │ Phase 0 (concurrent, independent)      │
   │  crt-sh   apollo   github-org   gleif  │
   │  passive-dns   reverse-whois           │
   │  dns-brute*  dns-zone-transfer*        │
   │  doh-enum*  favicon-hash*              │
   │  asn-bgp                               │
   └──────────┬─────────────────────────────┘
              │ Emits domains + CIDRs directly
   ┌──────────┴─────────────────────────────┐
   │ Phase 1 (concurrent)                   │
   │  whois   edgar                         │
   └──────────┬─────────────────────────────┘
              │ Emits RIR org handles
              ▼
       enrichWithHandles()
   Input.Meta["arin_handles"] = "ACME-1"
   Input.Meta["ripe_handles"] = "