Contributing to Pius

We welcome contributions to Pius. The most common contribution is adding a new discovery plugin.

How to add a new plugin to Pius

1. Create a Go file in the appropriate package:

   • Domain plugins: pkg/plugins/domains/
   • CIDR plugins: pkg/plugins/cidrs/

2. Implement the plugins.Plugin interface (7 methods):

   Method	Purpose
   Name()	Unique plugin identifier
   Description()	Human-readable description
   Category()	"cidr" or "domain"
   Phase()	0 (independent), 1 (handle discovery), or 2 (handle resolution)
   Mode()	"passive" (OSINT) or "active" (sends probes)
   Accepts(Input)	Return false to self-disable (missing API keys, inputs, etc.)
   Run(ctx, Input)	Execute discovery; must respect context cancellation

3. Register via init():

   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 existing plugins like crt_sh.go or arin.go for reference implementations.

Error handling conventions

Scenario	Convention
Transient failures (network timeout, 5xx)	Return (nil, nil) for graceful degradation
Parse errors	Return wrapped error with context
Partial failures	Log with slog.Warn() and continue

Plugin errors are logged but never fail the pipeline. Partial results from other plugins are always returned.

Development commands

# Run all tests
go test ./...

# Run specific package tests
go test ./pkg/plugins/domains/... -v

# Build binary
go build -o pius ./cmd/pius

# Install to $GOPATH/bin
go install ./cmd/pius

Testing guidelines

Write unit tests covering:

• Accepts() - verify correct self-disabling behavior
• Run() - verify correct output for mocked responses
• Error paths - verify graceful degradation
• Caching (if applicable) - verify cache hit/miss behavior

Use httptest.Server for mocking HTTP responses. Use the httpDoer interface pattern for testability (see RDAP plugins for examples).

Security

Pius is designed for authorized security testing and asset discovery only. Never run against organizations you don't own or have explicit permission to assess. Report security issues via GitHub Issues.

Related pages

• Architecture - Understand the pipeline before adding plugins
• Plugins - See existing plugins for reference
• FAQ - Common questions about plugin development