authentication

package
v0.5.2 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultLoginBudget = 2 * time.Minute

DefaultLoginBudget bounds the time ALL login flows together may take. It is a total, not a per-request timeout (each request keeps its own 30s): a scan configured with six sessions, each a three-step flow, could otherwise spend nine minutes in setup before sending a single scan request, with no output and no way to tell a slow login from a hung one. Two minutes is many times what a working login needs and short enough that a wedged one is a visible delay rather than an apparent hang.

Variables

This section is empty.

Functions

func IsRawHTTPRequest 

func IsRawHTTPRequest(data []byte) bool

IsRawHTTPRequest returns true if the data looks like a raw HTTP request.

func NormalizeLoginFlow 

func NormalizeLoginFlow(lf *LoginFlow)

NormalizeLoginFlow expands shorthand type/token_path into explicit extract rules and validates the URL. Called before execution; safe to call multiple times.

func ProbeLogin 

func ProbeLogin(sess *Session) (statusCode int, err error)

ProbeLogin sends the login request on a background context with no transport of its own. It is the convenience wrapper for the interactive `session` commands; a scan should use ProbeLoginContext so the probe follows the scan's proxy and cancellation.

func ProbeLoginContext added in v0.5.2 

func ProbeLoginContext(ctx context.Context, sess *Session, client *http.Client) (statusCode int, err error)

ProbeLoginContext sends the login request and returns the HTTP status code. Unlike executeLogin, it does not fail on non-2xx status codes — it returns the status code and lets the caller decide. If extract rules are present and the status is 2xx/3xx, it also runs extraction to populate session headers. Returns an error only on network/request-building failures.

ctx bounds the probe; client supplies the transport (proxy, target TLS) and is copied, never mutated. A nil client keeps Go's default transport.

func ValidateExpect 

func ValidateExpect(expect *ExpectResponse, statusCode int, body []byte) error

ValidateExpect checks if an HTTP response satisfies the expect constraints.

Types

type DiscoverResult 

type DiscoverResult struct {
	Session      *Session
	StatusCode   int
	TokenSources []string // human-readable descriptions of where tokens were found
	RawResponse  string   // raw response for storage in login_response
}

DiscoverResult holds the output of auto-discovery.

func DiscoverLogin 

func DiscoverLogin(loginReq *LoginRequest) (*DiscoverResult, error)

DiscoverLogin sends the given login request and auto-discovers auth tokens from the response. It checks JSON body fields, Set-Cookie headers, and auth response headers. Returns a Session with a LoginFlow populated with auto-generated ExtractRules.

type ExpectResponse 

type ExpectResponse struct {
	Status       []int  `yaml:"status,omitempty" json:"status,omitempty"`               // Acceptable status codes (e.g. [200, 201])
	BodyContains string `yaml:"body_contains,omitempty" json:"body_contains,omitempty"` // Response body must contain this string
}

ExpectResponse defines validation rules for a login response.

type ExtractRule 

type ExtractRule struct {
	Source  ExtractSource `yaml:"source" json:"source"`
	Name    string        `yaml:"name,omitempty" json:"name,omitempty"`         // Cookie name or header name
	Path    string        `yaml:"path,omitempty" json:"path,omitempty"`         // JSONPath for json source
	ApplyAs string        `yaml:"apply_as,omitempty" json:"apply_as,omitempty"` // Header template, e.g. "Authorization: Bearer {value}"
	// Regex extraction fields (source: "regex")
	Pattern string `yaml:"pattern,omitempty" json:"pattern,omitempty"` // Regex pattern with capture group
	Group   int    `yaml:"group,omitempty" json:"group,omitempty"`     // Capture group index (default: 1)
}

ExtractRule defines how to extract an auth token from a login response.

type ExtractSource 

type ExtractSource string

ExtractSource specifies where to extract authentication tokens from a login response. 

const (
	ExtractCookie ExtractSource = "cookie" // Extract from Set-Cookie header
	ExtractJSON   ExtractSource = "json"   // Extract from JSON response body
	ExtractHeader ExtractSource = "header" // Extract from response header
	ExtractRegex  ExtractSource = "regex"  // Extract from response body via regex
)

type LintIssue 

type LintIssue struct {
	Field    string // dot-notation path, e.g. "sessions[0].login.url"
	Severity string // "error" or "warning"
	Message  string
}

LintIssue represents a single validation issue found during linting.

func LintSessionConfig 

func LintSessionConfig(cfg *SessionConfig) []LintIssue

LintSessionConfig performs detailed validation of a SessionConfig and returns all issues found, rather than stopping at the first error.

type LoginFlow 

type LoginFlow struct {
	URL         string        `yaml:"url" json:"url"`
	Method      string        `yaml:"method" json:"method"`
	ContentType string        `yaml:"content_type,omitempty" json:"content_type,omitempty"`
	Body        string        `yaml:"body,omitempty" json:"body,omitempty"`
	Extract     []ExtractRule `yaml:"extract,omitempty" json:"extract,omitempty"`
	// Shorthand: type + token_path expand into extract rules automatically.
	Type      LoginType `yaml:"type,omitempty" json:"type,omitempty"`
	TokenPath string    `yaml:"token_path,omitempty" json:"token_path,omitempty"`
	// Response validation.
	Expect *ExpectResponse `yaml:"expect,omitempty" json:"expect,omitempty"`
	// Multi-step login flows. When set, URL/Method/Body/Extract on the parent are ignored.
	Steps []LoginStep `yaml:"steps,omitempty" json:"steps,omitempty"`
}

LoginFlow defines how to authenticate to get session credentials.

func (*LoginFlow) LoginURL 

func (lf *LoginFlow) LoginURL() string

LoginURL returns the login URL for the session. For multi-step flows, returns the URL of the first step.

func (*LoginFlow) Validate 

func (lf *LoginFlow) Validate(sessionName string) error

Validate checks that a LoginFlow is well-formed.

type LoginRequest 

type LoginRequest struct {
	Method  string
	URL     string
	Headers map[string]string
	Body    string
	Raw     string // original raw request text
}

LoginRequest holds a parsed raw HTTP login request.

func ParseRawLoginRequest 

func ParseRawLoginRequest(raw string) (*LoginRequest, error)

ParseRawLoginRequest parses a raw HTTP request string into a LoginRequest. Supports the format: 

POST /rest/user/login HTTP/1.1
Host: localhost:3000
Content-Type: application/json

{"email":"admin@juice-sh.op","password":"admin123"}

type LoginStep 

type LoginStep struct {
	URL         string          `yaml:"url" json:"url"`
	Method      string          `yaml:"method" json:"method"`
	ContentType string          `yaml:"content_type,omitempty" json:"content_type,omitempty"`
	Body        string          `yaml:"body,omitempty" json:"body,omitempty"`
	Extract     []ExtractRule   `yaml:"extract,omitempty" json:"extract,omitempty"`
	Expect      *ExpectResponse `yaml:"expect,omitempty" json:"expect,omitempty"`
}

LoginStep defines a single step in a multi-step login flow.

type LoginType 

type LoginType string

LoginType is a shorthand preset that auto-expands into extract rules. 

const (
	LoginTypeBearer LoginType = "bearer" // JSON body → Authorization: Bearer {value}
	LoginTypeCookie LoginType = "cookie" // Capture all Set-Cookie headers
)

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager loads, validates, and hydrates sessions for multi-session scanning.

func NewManager 

func NewManager(sessions []*Session, opts ...ManagerOption) (*Manager, error)

NewManager creates a Manager from the resolved session list.

func (*Manager) AllSessions 

func (m *Manager) AllSessions() []*Session

AllSessions returns all sessions.

func (*Manager) CompareSessions 

func (m *Manager) CompareSessions() []*Session

CompareSessions returns all non-primary sessions used for comparison.

func (*Manager) HydrateSessions 

func (m *Manager) HydrateSessions() error

HydrateSessions executes login flows for sessions that need them on a background context. It is the convenience wrapper for callers with no context of their own; anything inside a scan should call HydrateSessionsContext so a cancelled scan stops logging in.

func (*Manager) HydrateSessionsContext added in v0.5.2 

func (m *Manager) HydrateSessionsContext(ctx context.Context) error

HydrateSessionsContext executes login flows for sessions that need them, bounded by ctx AND by the manager's total login budget (whichever expires first). The budget wraps the WHOLE loop rather than each session, so N sessions cannot cost N × the budget; a flow that runs out mid-way reports which session it died on.

A cancelled or expired ctx is reported before the first request, so a cancelled scan does not start a login it is about to abandon.

func (*Manager) Primary 

func (m *Manager) Primary() *Session

Primary returns the primary session.

func (*Manager) PrimaryHeaders 

func (m *Manager) PrimaryHeaders() []string

PrimaryHeaders returns the primary session's headers as a slice for types.Options.Headers.

type ManagerOption 

type ManagerOption func(*Manager)

ManagerOption configures optional Manager behavior.

func WithLoginBudget added in v0.5.2 

func WithLoginBudget(d time.Duration) ManagerOption

WithLoginBudget overrides the total time all login flows together may take. A non-positive value keeps DefaultLoginBudget.

func WithLoginTransport added in v0.5.2 

func WithLoginTransport(rt http.RoundTripper) ManagerOption

WithLoginTransport routes login requests over rt. A login request targets the host the scan is about to attack, so it belongs on the same proxy and the same permissive TLS stance as the rest of the scan's traffic; pkg/http.LoginTransport builds exactly that. A nil rt is ignored (Go's default transport stands).

func WithSessionDir 

func WithSessionDir(dir string) ManagerOption

WithSessionDir overrides the default directory used to resolve session file names.

type Role 

type Role string

Role identifies how a session is used during scanning. 

const (
	// RolePrimary drives discovery and spidering — the "owner" of the resources.
	RolePrimary Role = "primary"
	// RoleCompare is replayed during audit phase for cross-session comparison.
	RoleCompare Role = "compare"
)

type Session 

type Session struct {
	Name    string            `yaml:"name" json:"name"`
	Role    Role              `yaml:"role" json:"role"`
	Headers map[string]string `yaml:"headers,omitempty" json:"headers,omitempty"`
	Login   *LoginFlow        `yaml:"login,omitempty" json:"login,omitempty"`
	// LoginRequest is a raw HTTP request string for the login flow.
	LoginRequest string `yaml:"login_request,omitempty" json:"login_request,omitempty"`
	// contains filtered or unexported fields
}

Session represents a named authentication identity used during scanning.

func LoadFromAuthFiles 

func LoadFromAuthFiles(paths []string, sessionDir string) ([]*Session, error)

LoadFromAuthFiles loads sessions from one or more --auth-file values. Each value is either a file path (YAML/JSON, single session or sessions: bundle) or a bare name resolved against sessionDir (default ~/.vigolium/sessions/), trying .yaml, .yml, .json in order. Files support ${ENV} expansion before parsing.

func LoadFromAuthInline 

func LoadFromAuthInline(values []string) ([]*Session, error)

LoadFromAuthInline parses --auth values in "name:Header:value" format.

func ParseInlineSession 

func ParseInlineSession(s string) (*Session, error)

ParseInlineSession parses a CLI --auth flag value in "name:Header:value" format. Example: "admin:Cookie:session=abc" → Session{Name:"admin", Headers:{"Cookie":"session=abc"}}

func (*Session) HeaderSlice 

func (s *Session) HeaderSlice() []string

HeaderSlice converts the session headers map to a slice of "Name: Value" strings, compatible with types.Options.Headers.

func (*Session) IsHydrated 

func (s *Session) IsHydrated() bool

IsHydrated returns true if the session has been populated with credentials.

func (*Session) Validate 

func (s *Session) Validate() error

Validate checks that the session definition is well-formed.

type SessionConfig 

type SessionConfig struct {
	Sessions []Session `yaml:"sessions" json:"sessions"`
}

SessionConfig holds multiple sessions, used for --auth-config files (YAML or JSON).

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.