sdk

package
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 3, 2026 License: AGPL-3.0 Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CrashSafe         = "CRASH_SAFE"
	CrashUnsafe       = "CRASH_UNSAFE"
	ServiceRestart    = "SERVICE_RESTART"
	ArtifactsOnDisk   = "ARTIFACTS_ON_DISK"
	IOCInLogs         = "IOC_IN_LOGS"
	ConfigChanges     = "CONFIG_CHANGES"
	RepeatableSession = "REPEATABLE_SESSION"
	AccountLockout    = "ACCOUNT_LOCKOUT_POSSIBLE"
)

Standard stability tags.

Variables

This section is empty.

Functions

func Base64Decode added in v0.2.0 

func Base64Decode(s string) (string, error)

Base64Decode decodes a base64 string.

func Base64Encode added in v0.2.0 

func Base64Encode(s string) string

Base64Encode encodes a string to base64.

func CanCheck 

func CanCheck(mod Exploit) bool

CanCheck returns true if the module implements Checker.

func Contains added in v0.2.0 

func Contains(s, substr string) bool

Contains checks if s contains substr.

func ContainsI added in v0.4.0 

func ContainsI(s, substr string) bool

ContainsI checks if s contains substr (case-insensitive).

func Dedent 

func Dedent(s string) string

Dedent strips the common leading whitespace from all non-empty lines.

func Errorf 

func Errorf(format string, args ...any) error

Errorf is fmt.Errorf, re-exported so modules don't need to import fmt.

func HasOpt 

func HasOpt(opts []Option, name string) bool

func HasOption 

func HasOption(mod Exploit, name string) bool

HasOption returns true if the module declares an option with the given name.

func IsRand added in v0.3.0 

func IsRand(v string) (string, bool)

IsRand checks if a value is a Rand placeholder and returns the label.

func JSONBody added in v0.2.0 

func JSONBody(v any) string

JSONBody serializes a value to a JSON string for use in Request.Body.

func Multipart added in v0.2.0 

func Multipart(parts map[string]string) (string, string)

Multipart builds a multipart/form-data body from named parts (unordered). Returns the body string and content-type header.

func MultipartOrdered added in v0.2.0 

func MultipartOrdered(boundary string, parts ...string) (string, string)

MultipartOrdered builds a multipart/form-data body from ordered name-value pairs. Parts are provided as alternating name, value strings. Returns the body string and content-type header.

func NameOf 

func NameOf(mod Exploit) string

NameOf returns the registered name of an exploit.

func Names 

func Names() []string

Names returns all registered exploit names in order.

func ObfuscateEmail added in v0.2.0 

func ObfuscateEmail(email string) string

ObfuscateEmail formats a raw email to <user[at]domain>. Already obfuscated emails are returned as-is.

func Rand added in v0.3.0 

func Rand(label string) string

Rand returns a placeholder that pkg/lab replaces with a random value. Same label across services = same generated value (shared credentials).

func RandInt added in v0.2.0 

func RandInt(min, max int) int

RandInt returns a random int between min and max (inclusive).

func RandTextDefault added in v0.2.0 

func RandTextDefault(n int) string

RandTextDefault generates random alphanumeric text without needing a Context.

func RegexFind added in v0.2.0 

func RegexFind(pattern, s string) string

RegexFind returns the first capturing group match of pattern in s, or empty string.

func Register 

func Register(mod Exploit)

Register adds an exploit to the global registry. The name is derived from the caller's file path relative to modules/. callerSkip controls stack depth: use 0 when calling from init() directly, use 1 when called through an intermediary (like sdk.Register wrapper).

func RegisterEnricher 

func RegisterEnricher(fn OptionEnricher)

func Replace added in v0.2.0 

func Replace(s string, oldNew ...string) string

Replace creates a string replacer and applies it.

func Run 

func Run(mod Exploit, opts ...RunOption)

Run starts a standalone single-module CLI. Requires importing _ "github.com/Chocapikk/pik/pkg/cli" to register the runner.

func SendWith added in v0.4.0 

func SendWith(params Params) func(Request) (*Response, error)

SendWith creates an HTTP send function using the registered factory.

func SetDialFactory added in v0.4.0 

func SetDialFactory(f DialFactory)

SetDialFactory registers the TCP dial implementation. Called by pkg/protocol/tcp's init().

func SetLabManager added in v0.2.0 

func SetLabManager(m LabManager)

SetLabManager registers the lab manager (called from pkg/lab init).

func SetPoolFactory added in v0.4.0 

func SetPoolFactory(f PoolFactory)

SetPoolFactory registers the connection pool implementation.

func SetRunner 

func SetRunner(fn func(Exploit, RunOptions))

SetRunner registers the standalone runner function. Called from pkg/cli's init() to break the import cycle.

func SetSendFactory added in v0.4.0 

func SetSendFactory(f SendFactory)

SetSendFactory registers the HTTP send implementation. Called by pkg/protocol/http's init().

func Sprintf 

func Sprintf(format string, args ...any) string

Sprintf is fmt.Sprintf, re-exported so modules don't need to import fmt.

func WithPool added in v0.4.0 

func WithPool(ctx context.Context, threads int, proxy string) context.Context

WithPool applies connection pooling if a factory is registered. Returns ctx unchanged if no pool factory is available (e.g. TCP modules).

Types

type Author added in v0.2.0 

type Author struct {
	Name    string // real name or alias
	Handle  string // online handle (e.g. "Chocapikk")
	Email   string // contact email, must use <user[at]domain> format (Register panics on raw @)
	Company string // organization or team (e.g. "Horizon3 Attack Team")
}

Author describes a module contributor. Email is automatically formatted to <user[at]domain> for anti-scraping.

func (Author) String added in v0.2.0 

func (a Author) String() string

type AuthorRank 

type AuthorRank struct {
	Name    string
	Modules int
	CVEs    int
}

AuthorRank holds contributor statistics.

func Rankings 

func Rankings() []AuthorRank

Rankings returns a sorted leaderboard of exploit authors.

type Buffer added in v0.4.0 

type Buffer = encode.Buffer

Buffer is a fluent binary packet builder for crafting protocol messages. Re-exported from pkg/encode.

func NewBuffer added in v0.4.0 

func NewBuffer() *Buffer

NewBuffer creates a new binary packet builder.

type CheckCode 

type CheckCode int
const (
	CheckUnknown CheckCode = iota
	CheckSafe
	CheckDetected
	CheckAppears
	CheckVulnerable
)

func (CheckCode) IsVulnerable 

func (c CheckCode) IsVulnerable() bool

func (CheckCode) String 

func (c CheckCode) String() string

type CheckResult 

type CheckResult struct {
	Code    CheckCode
	Reason  string
	Details map[string]string // version detected, banner, etc.
}

func Detected 

func Detected(reason string) (CheckResult, error)

func Safe 

func Safe(reason string) (CheckResult, error)

func Unknown 

func Unknown(err error) (CheckResult, error)

func Vulnerable 

func Vulnerable(reason string, details ...string) (CheckResult, error)

Check result constructors - match MSF's CheckCode::Vulnerable() style.

func (CheckResult) FormatReason 

func (r CheckResult) FormatReason() string

type Checker 

type Checker interface {
	Check(run *Context) (CheckResult, error)
}

Checker is an optional interface for modules that support vulnerability checking.

type CmdStager 

type CmdStager interface {
	ExecuteCommand(run *Context, cmd string) error
}

CmdStager is a marker interface for modules that support chunked command delivery. When the runner uses cmdstager mode, it sets commands on the Context via SetCommands(). The module reads them with Commands() and delivers them in its Exploit() method, handling its own setup/teardown.

type Conn added in v0.4.0 

type Conn interface {
	Send([]byte) error
	Recv(int) ([]byte, error)
	SendRecv(data []byte, recvSize int) ([]byte, error)
	Close() error
}

Conn is a raw TCP connection returned by Dial.

func DialWith added in v0.4.0 

func DialWith(params Params) (Conn, error)

DialWith creates a Conn using the registered factory.

type Context 

type Context struct {

	// Function hooks injected by the runner.
	SendFn       func(Request) (*Response, error)
	DialFn       func() (Conn, error)
	StatusFn     func(string, ...any)
	SuccessFn    func(string, ...any)
	ErrorFn      func(string, ...any)
	WarningFn    func(string, ...any)
	Base64BashFn func(string) string
	CommentFn    func(string) string
	RandTextFn   func(int) string
	// contains filtered or unexported fields
}

Context is the execution context passed to exploits. Provides HTTP, logging, payload helpers, and timing.

func NewContext 

func NewContext(values map[string]string, payload string) *Context

NewContext creates a Context with option values and payload command.

func (*Context) Base64Bash 

func (c *Context) Base64Bash(cmd string) string

func (*Context) Commands 

func (c *Context) Commands() []string

Commands returns the CmdStager commands set by the runner. Empty when in single-shot mode.

func (*Context) CommentTrail 

func (c *Context) CommentTrail(cmd string) string

func (*Context) Dial added in v0.4.0 

func (c *Context) Dial() (Conn, error)

Dial opens a raw TCP connection to the target.

func (*Context) Elapsed 

func (c *Context) Elapsed(start bool) float64

func (*Context) Error 

func (c *Context) Error(format string, args ...any)

func (*Context) Get 

func (c *Context) Get(key string) string

func (*Context) Params added in v0.4.0 

func (c *Context) Params() Params

Params returns an sdk.Params built from the context values. Used by TCP modules to pass to tcp.FromModule().

func (*Context) Payload 

func (c *Context) Payload() string

func (*Context) RandText 

func (c *Context) RandText(n int) string

func (*Context) Send 

func (c *Context) Send(req Request) (*Response, error)

Send dispatches an HTTP request through the runner's HTTP bridge.

func (*Context) SetCommands 

func (c *Context) SetCommands(cmds []string)

SetCommands is called by the runner to inject CmdStager commands.

func (*Context) SetTarget 

func (c *Context) SetTarget(t Target)

SetTarget is called by the runner to set the active target.

func (*Context) Status 

func (c *Context) Status(format string, args ...any)

func (*Context) Success 

func (c *Context) Success(format string, args ...any)

func (*Context) Target 

func (c *Context) Target() Target

Target returns the selected target from module metadata.

func (*Context) Warning 

func (c *Context) Warning(format string, args ...any)

type DialFactory added in v0.4.0 

type DialFactory func(Params) (Conn, error)

DialFactory creates a Conn from module params. Registered by pkg/protocol/tcp via SetDialFactory.

type Exploit 

type Exploit interface {
	Info() Info
	Options() []Option
	Exploit(run *Context) error
}

Exploit is the interface all modules must implement.

func Get 

func Get(name string) Exploit

Get returns an exploit by full path or short name.

func List 

func List() []Exploit

List returns all registered exploits in registration order. 

func Search(query string) []Exploit

Search returns exploits matching query against name, description, or CVEs.

type Info 

type Info struct {
	Name           string // Software name (e.g. "OpenDCIM", "Langflow", "Next.js")
	Versions       string // Affected versions (e.g. "< 24.2", "1.0.0 - 1.2.9")
	Description    string // Vulnerability title (e.g. "SQLi to RCE via Config Poisoning")
	Detail         string
	Authors        []Author
	DisclosureDate string // "2026-01-15"
	Reliability    Reliability
	Stance         Stance
	Privileged     bool // does exploitation yield privileged access?
	Notes          Notes
	References     []Reference
	Queries        []Query
	Targets        []Target
	DefaultOptions map[string]string
	Lab            Lab
}

func (Info) AuthorNames added in v0.2.0 

func (info Info) AuthorNames() string

func (Info) CVEs 

func (info Info) CVEs() []string

func (Info) Platform 

func (info Info) Platform() string

func (Info) TargetStrings 

func (info Info) TargetStrings() []string

func (Info) Title added in v0.2.0 

func (info Info) Title() string

Title returns the formatted module title: "Name Versions - Description".

type Lab added in v0.2.0 

type Lab struct {
	Services []Service
}

Lab declares an optional Docker lab environment for testing a module.

type LabManager added in v0.2.0 

type LabManager interface {
	Start(ctx context.Context, name string, services []Service) error
	Stop(ctx context.Context, name string) error
	Status(ctx context.Context) ([]LabStatus, error)
	IsRunning(ctx context.Context, name string) bool
	Target(ctx context.Context, name string) string
	WaitReady(ctx context.Context, addr string, timeout time.Duration) error
	WaitProbe(ctx context.Context, timeout time.Duration, fn func() error) error
	DockerGateway() string
}

LabManager is implemented by pkg/lab and registered via SetLabManager. This late binding keeps Docker SDK out of the sdk package and out of standalone binaries that don't import pkg/lab.

func GetLabManager added in v0.2.0 

func GetLabManager() LabManager

GetLabManager returns the registered lab manager, or nil if not available.

type LabServiceStatus added in v0.2.0 

type LabServiceStatus struct {
	Name  string
	Image string
	State string
	Ports string
}

LabServiceStatus holds status for one service container.

type LabStatus added in v0.2.0 

type LabStatus struct {
	Name     string
	Services []LabServiceStatus
}

LabStatus holds status for a lab (mirrors lab.LabInfo without importing it).

type Notes 

type Notes struct {
	Stability   []string // CRASH_SAFE, CRASH_UNSAFE, SERVICE_RESTART
	SideEffects []string // ARTIFACTS_ON_DISK, IOC_IN_LOGS, CONFIG_CHANGES
	Reliability []string // REPEATABLE_SESSION, UNRELIABLE_SESSION
}

type Option 

type Option struct {
	Name     string
	Type     OptionType // defaults to TypeString if empty
	Default  string
	Desc     string
	Required bool
	Advanced bool
	Enums    []string // valid values for TypeEnum
}

func OptAddress 

func OptAddress(name, def, desc string) Option

func OptAdvanced 

func OptAdvanced(opt Option) Option

OptAdvanced marks any option as advanced.

func OptBool 

func OptBool(name string, def bool, desc string) Option

func OptEnum 

func OptEnum(name, def, desc string, values ...string) Option

func OptInt 

func OptInt(name string, def int, desc string) Option

func OptPort 

func OptPort(name string, def int, desc string) Option

func OptRequired 

func OptRequired(name, def, desc string) Option

func OptString 

func OptString(name, def, desc string) Option

func OptTargetURI 

func OptTargetURI(def string) Option

func ResolveOptions 

func ResolveOptions(mod Exploit) []Option

ResolveOptions returns the full option set: module + enrichers + target defaults + module defaults.

func (Option) Validate 

func (o Option) Validate(val string) error

Validate checks if a value is valid for this option.

type OptionEnricher 

type OptionEnricher func(mod Exploit, opts []Option) []Option

type OptionType 

type OptionType string
const (
	TypeString  OptionType = "string"
	TypeInt     OptionType = "int"
	TypeBool    OptionType = "bool"
	TypePort    OptionType = "port"
	TypePath    OptionType = "path"
	TypeAddress OptionType = "address"
	TypeEnum    OptionType = "enum"
)

type Params 

type Params struct {
	Ctx context.Context
	// contains filtered or unexported fields
}

Params holds the resolved option values for a module run.

func NewParams 

func NewParams(ctx context.Context, values map[string]string) Params

NewParams creates a Params with initial values.

func (Params) Arch 

func (p Params) Arch() string

Arch returns the ARCH parameter, defaulting to "amd64".

func (Params) Clone 

func (p Params) Clone() Params

Clone returns a copy of Params with an independent values map.

func (Params) Get 

func (p Params) Get(key string) string

Get returns the value of a parameter.

func (Params) GetOr 

func (p Params) GetOr(key, def string) string

GetOr returns the value of a parameter, or a default if not set.

func (Params) Int 

func (p Params) Int(key string) int

Int returns the value as an integer, or 0 if not parseable.

func (Params) IntOr 

func (p Params) IntOr(key string, def int) int

IntOr returns the value as an integer, or a default if not parseable.

func (Params) Lhost 

func (p Params) Lhost() string

Lhost returns the LHOST parameter.

func (Params) Lport 

func (p Params) Lport() int

Lport returns the LPORT parameter as an integer.

func (Params) Map 

func (p Params) Map() map[string]string

Map returns a copy of all parameter values.

func (Params) Set 

func (p Params) Set(key, value string)

Set sets a parameter value.

func (Params) Srvhost 

func (p Params) Srvhost() string

Srvhost returns the local bind address. Falls back to LHOST.

func (Params) Srvport 

func (p Params) Srvport() int

Srvport returns the local bind port. Falls back to LPORT.

func (Params) Target 

func (p Params) Target() string

Target returns the TARGET parameter.

func (Params) Tunnel 

func (p Params) Tunnel() string

Tunnel returns the tunnel URL if set.

type Pik 

type Pik struct{}

Pik is the base struct embedded by all modules. It provides default implementations for optional interface methods.

func (Pik) Options 

func (Pik) Options() []Option

Options returns the module's declared options (none by default).

type PoolFactory added in v0.4.0 

type PoolFactory func(ctx context.Context, threads int, proxy string) context.Context

PoolFactory configures connection pooling on a context for concurrent scanning. Registered by protocol packages that support pooling (e.g. HTTP).

type Query 

type Query struct {
	Engine string
	Dork   string
	Scope  string // optional, e.g. "service" or "leak" for LeakIX
}

Query is a search engine dork for finding targets.

func Censys 

func Censys(dork string) Query

func FOFA 

func FOFA(dork string) Query

func Google 

func Google(dork string) Query

func Hunter 

func Hunter(dork string) Query

func LeakIX 

func LeakIX(dork, scope string) Query

func Shodan 

func Shodan(dork string) Query

func ZoomEye 

func ZoomEye(dork string) Query

func (Query) URL 

func (q Query) URL() string

URL returns the direct search URL for this query.

type RefType 

type RefType string

RefType identifies the kind of reference. 

const (
	RefCVE         RefType = "CVE"
	RefGHSA        RefType = "GHSA"
	RefEDB         RefType = "EDB"
	RefPacketstorm RefType = "PACKETSTORM"
	RefVulnCheck   RefType = "VULNCHECK"
	RefURL         RefType = "URL"
)

type Reference 

type Reference struct {
	Type RefType
	ID   string
	Repo string // optional: "owner/repo" for repo-scoped advisories (GHSA)
}

Reference is a vulnerability reference.

func CVE 

func CVE(id string) Reference

func EDB 

func EDB(id string) Reference

func GHSA 

func GHSA(id string, repo ...string) Reference

GHSA creates a GitHub Security Advisory reference. Use GHSA("xxxx-yyyy-zzzz") for global advisories, or GHSA("xxxx-yyyy-zzzz", "owner/repo") for repo-scoped ones.

func Packetstorm 

func Packetstorm(id string) Reference

func URL 

func URL(u string) Reference

func VulnCheck 

func VulnCheck(slug string) Reference

func (Reference) String 

func (r Reference) String() string

func (Reference) URL 

func (r Reference) URL() string

URL returns the full URL for this reference.

type Reliability 

type Reliability int
const (
	Unstable     Reliability = 0
	Unlikely     Reliability = 100
	Difficult    Reliability = 200
	Typical      Reliability = 300
	Reliable     Reliability = 400
	VeryReliable Reliability = 500
	Certain      Reliability = 600
)

func (Reliability) String 

func (r Reliability) String() string

type Request 

type Request struct {
	Method        string
	Path          string
	Query         Values
	Form          Values
	Body          string // raw request body
	ContentType   string
	Headers       map[string]string
	Timeout       int // seconds
	NoRedirect    bool
	FireAndForget bool // send request, ignore response and errors
}

Request describes an HTTP request from module code.

func (*Request) BodyReader added in v0.2.0 

func (r *Request) BodyReader() io.Reader

BodyReader returns the Body as an io.Reader. Used internally by the HTTP bridge.

type Response 

type Response struct {
	StatusCode int
	Body       io.ReadCloser
	Headers    map[string]string
	// contains filtered or unexported fields
}

Response is an HTTP response for module code.

func (*Response) BodyBytes added in v0.2.0 

func (r *Response) BodyBytes() ([]byte, error)

BodyBytes reads and caches the full response body.

func (*Response) BodyString added in v0.2.0 

func (r *Response) BodyString() (string, error)

BodyString returns the response body as a string.

func (*Response) Contains added in v0.2.0 

func (r *Response) Contains(substr string) bool

Contains checks if the response body contains the given substring.

func (*Response) ContainsAny 

func (r *Response) ContainsAny(substrs ...string) bool

ContainsAny returns true if the response body contains any of the given substrings.

func (*Response) Header added in v0.2.0 

func (r *Response) Header(key string) string

Header returns the value of a response header (case-insensitive).

func (*Response) JSON added in v0.2.0 

func (r *Response) JSON(target any) error

JSON unmarshals the response body into the given target.

func (*Response) SetContainsFn 

func (r *Response) SetContainsFn(fn func(...string) bool)

SetContainsFn sets the function used by ContainsAny.

type RunOption added in v0.1.4 

type RunOption func(*RunOptions)

RunOption is a functional option for Run.

func WithConsole added in v0.1.4 

func WithConsole() RunOption

WithConsole enables the interactive console subcommand in standalone binaries.

func WithLab added in v0.2.0 

func WithLab() RunOption

WithLab enables lab management subcommands in standalone binaries. Requires importing _ "github.com/Chocapikk/pik/pkg/lab" to register the backend.

type RunOptions added in v0.1.4 

type RunOptions struct {
	Console bool // Add interactive console subcommand.
	Lab     bool // Add lab management subcommands.
}

RunOptions configures standalone binary behavior.

type SendFactory added in v0.4.0 

type SendFactory func(Params) func(Request) (*Response, error)

SendFactory creates a SendFn from module params. Registered by pkg/protocol/http via SetSendFactory.

type Service added in v0.2.0 

type Service struct {
	Name        string            // container name suffix (e.g. "web", "db")
	Image       string            // Docker image (e.g. "vulhub/langflow:1.2.0")
	Ports       []string          // port bindings (e.g. "7860:7860")
	Env         map[string]string // environment variables
	Cmd         []string          // override entrypoint command
	Volumes     []string          // bind mounts (host:container)
	Healthcheck []string          // CMD-SHELL health check command
}

Service describes a container in a lab environment. pkg/lab converts these to Docker SDK types at runtime.

func NewLabService added in v0.2.0 

func NewLabService(name, image string, ports ...string) Service

NewLabService builds a Service for the common case: image + port bindings. Chain WithEnv(), WithCmd(), WithVolume(), and WithHealthcheck() for more.

func (Service) WithCmd added in v0.2.0 

func (s Service) WithCmd(args ...string) Service

WithCmd overrides the container command.

func (Service) WithEnv added in v0.2.0 

func (s Service) WithEnv(key, value string) Service

WithEnv adds an environment variable.

func (Service) WithHealthcheck added in v0.2.0 

func (s Service) WithHealthcheck(cmd string) Service

WithHealthcheck sets a CMD-SHELL health check.

func (Service) WithVolume added in v0.2.0 

func (s Service) WithVolume(bind string) Service

WithVolume adds a bind mount (host:container).

type Stance 

type Stance string
const (
	Aggressive Stance = "aggressive" // may crash target or leave artifacts
	Passive    Stance = "passive"    // read-only, no side effects
)

type Target 

type Target struct {
	Name           string
	Platform       string
	Type           string // module-defined, e.g. "cmd", "dropper"
	Arches         []string
	DefaultOptions map[string]string // per-target option overrides
}

func TargetLinux 

func TargetLinux(arches ...string) Target

func TargetWindows 

func TargetWindows(arches ...string) Target

func (Target) String 

func (t Target) String() string

func (Target) SupportsArch 

func (t Target) SupportsArch(arch string) bool

type Values 

type Values = map[string][]string

Values is a map of string slices, used for query/form parameters.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.