Pius FAQ - Frequently Asked Questions

Which plugins run by default?

All passive plugins that accept the provided input run by default. Passive plugins with API key requirements (apollo, passive-dns, reverse-whois) are silently skipped if their environment variable is not set. Active plugins (dns-brute, dns-zone-transfer, doh-enum, favicon-hash) only run with --mode active or --mode all.

How does the three-phase pipeline work?

Phase 0 plugins (domain plugins + asn-bgp) run immediately and concurrently. Phase 1 plugins (whois, edgar) discover RIR organization handles from the company name. The runner then injects those handles into the input as metadata, and Phase 2 plugins (arin, ripe, apnic, afrinic, lacnic) resolve each handle to CIDR blocks. This separation enables accurate multi-RIR coverage while keeping plugins loosely coupled.

See Architecture for the full pipeline diagram.

What does "needs-review" mean in the output?

Some plugins use confidence scoring to rank ambiguous matches. For example, github-org scores organization candidates based on name similarity and domain matching. Findings with confidence between 0.35 and 0.65 are emitted with a needs-review flag rather than being silently discarded. Findings below 0.35 are dropped as noise.

Can I run Pius without any API keys?

Yes. These plugins require no authentication and run with only --org:

• crt-sh (needs --domain), gleif, whois, edgar, wikidata, google-dorks
• arin, ripe, apnic, afrinic, lacnic
• asn-bgp (needs --asn)
• github-org (optional GITHUB_TOKEN for higher rate limits)
• dns-brute, dns-zone-transfer, doh-enum (active mode, no auth)

See Configuration for the full API key reference.

What is the difference between RDAP and RPSL plugins?

RDAP plugins (arin, ripe, lacnic) make live HTTP queries to each registry's RDAP API per RFC 7483. One request is made per handle, providing the freshest data.

RPSL plugins (apnic, afrinic) download the full registry database as a gzip file once per day and parse it locally. RPSL offers lower latency after the initial download but data may be up to 24 hours old.

How do I add a new plugin?

1. Create a Go file in pkg/plugins/domains/ or pkg/plugins/cidrs/
2. Implement the plugins.Plugin interface (7 methods: Name, Description, Category, Phase, Mode, Accepts, Run)
3. Register in an init() function:

   func init() {
       plugins.Register("my-plugin", func() plugins.Plugin {
           return &MyPlugin{client: client.New()}
       })
   }
   

4. Add a blank import to pkg/plugins/all/all.go

See Contributing for the full guide and conventions.

What output formats does Pius support?

Pius supports three output formats:

Format	Flag	Use Case
Terminal table	--output terminal (default)	Human-readable
JSON array	--output json	Structured parsing
NDJSON	--output ndjson	Streaming, piping to jq

Is Pius safe to run in production?

Yes. Pius defaults to passive mode, querying only OSINT data sources. Active plugins (DNS brute-force, zone transfer) must be explicitly enabled. The tool includes multi-tier caching, graceful degradation on errors, and never fails the pipeline due to a single plugin error.

Related pages

• Troubleshooting - Fix common issues
• Plugins - Full plugin reference
• Architecture - Pipeline internals