schemas

package
v0.1.7 Latest Latest
Warning

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

Go to latest
Published: Jan 5, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

schemas/browser.go

File: api/schemas/tasks.go

Index

Constants

This section is empty.

Variables

View Source
var DefaultPersona = Persona{

	UserAgent:   "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/109.0.0.0 Safari/536.36",
	Platform:    "Win32",
	Languages:   []string{"en-US", "en"},
	Width:       1920,
	Height:      1080,
	AvailWidth:  1920,
	AvailHeight: 1040,
	ColorDepth:  24,
	PixelDepth:  1,
	Mobile:      false,
	Timezone:    "America/Los_Angeles",
	Locale:      "en-US",
}

DefaultPersona provides a fallback persona if none is specified.

Functions

This section is empty.

Types

type ATOTaskParams

type ATOTaskParams struct {
	Usernames []string `json:"usernames"` // A list of usernames to test for vulnerabilities like password spraying.
}

ATOTaskParams provides the specific parameters required for an Account Takeover (ATO) analysis task.

type AgentMissionParams

type AgentMissionParams struct {
	MissionBrief string `json:"mission_brief"` // The high-level objective for the agent to achieve.
}

AgentMissionParams provides the parameters for a high-level agent mission.

type Artifacts

type Artifacts struct {
	HAR         *json.RawMessage `json:"har"`          // The HTTP Archive (HAR) data for network requests.
	DOM         string           `json:"dom"`          // The full HTML source of the page.
	ConsoleLogs []ConsoleLog     `json:"console_logs"` // A log of all console messages.
	Storage     StorageState     `json:"storage"`      // A snapshot of the browser's storage.
}

Artifacts is a comprehensive collection of all data gathered from a browser session or interaction, including network requests (HAR), the DOM tree, console logs, and storage state.

type BrowserInteractor

type BrowserInteractor interface {
	// NavigateAndExtract loads a URL and returns a list of all discovered links.
	NavigateAndExtract(ctx context.Context, url string) ([]string, error)
}

BrowserInteractor provides a simplified, high-level interface for common browser interactions, such as navigating to a page and extracting all links.

type BrowserManager

type BrowserManager interface {
	// NewAnalysisContext creates a new, isolated browser session tailored for
	// security analysis, complete with a specified persona and taint tracking
	// configuration.
	NewAnalysisContext(
		sessionCtx context.Context,
		cfg interface{},
		persona Persona,
		taintTemplate string,
		taintConfig string,
		findingsChan chan<- Finding,
	) (SessionContext, error)
	// Shutdown gracefully terminates all browser instances managed by this manager.
	Shutdown(ctx context.Context) error
}

BrowserManager is responsible for the lifecycle of browser instances. It can launch new browser processes and create isolated sessions (contexts) for analysis.

type ClientHints

type ClientHints struct {
	Platform        string                   `json:"platform"`
	PlatformVersion string                   `json:"platformVersion"`
	Architecture    string                   `json:"architecture"`
	Bitness         string                   `json:"bitness"`
	Mobile          bool                     `json:"mobile"`
	Brands          []*UserAgentBrandVersion `json:"brands"`
}

ClientHints encapsulates the User-Agent Client Hints data, which provides more detailed information about the browser and operating system than the traditional User-Agent string.

type ConsoleLog

type ConsoleLog struct {
	Type      string    `json:"type"`      // The type of console message (e.g., "log", "error").
	Timestamp time.Time `json:"timestamp"` // The time the message was logged.
	Text      string    `json:"text"`      // The content of the console message.
	Source    string    `json:"source,omitempty"`
	URL       string    `json:"url,omitempty"`  // The URL of the script that generated the message.
	Line      int64     `json:"line,omitempty"` // The line number in the script.
}

ConsoleLog captures a single message from the browser's JavaScript console, such as logs, errors, or warnings.

type Content

type Content struct {
	Size     int64  `json:"size"`               // The size of the content in bytes.
	MimeType string `json:"mimeType"`           // The MIME type of the content.
	Text     string `json:"text,omitempty"`     // The content text, if it's not binary.
	Encoding string `json:"encoding,omitempty"` // The encoding of the content (e.g., "base64").
}

Content describes the content of an HTTP response body.

type Cookie struct {
	Name     string         `json:"name"`
	Value    string         `json:"value"`
	Domain   string         `json:"domain"`
	Path     string         `json:"path"`
	Expires  float64        `json:"expires"`
	Size     int64          `json:"size"`
	HTTPOnly bool           `json:"httpOnly"`
	Secure   bool           `json:"secure"`
	Session  bool           `json:"session"`
	SameSite CookieSameSite `json:"sameSite,omitempty"`
}

Cookie represents a single HTTP cookie, containing its name, value, and associated metadata like domain, path, and security attributes.

type CookieSameSite

type CookieSameSite string

CookieSameSite specifies the SameSite attribute for an HTTP cookie, controlling whether it's sent with cross-site requests.

const (
	CookieSameSiteStrict CookieSameSite = "Strict" // The cookie is only sent for same-site requests.
	CookieSameSiteLax    CookieSameSite = "Lax"    // The cookie is sent for same-site requests and top-level navigations.
	CookieSameSiteNone   CookieSameSite = "None"   // The cookie is sent for all requests, but requires the Secure attribute.
)

Constants for the CookieSameSite attribute.

type Creator

type Creator struct {
	Name    string `json:"name"`    // The name of the creator application.
	Version string `json:"version"` // The version of the creator application.
}

Creator provides information about the application that generated the HAR file.

type Credential

type Credential struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

Credential represents a set of login credentials, typically a username and password combination, used for authentication.

type DiscoveryEngine

type DiscoveryEngine interface {
	// Start begins the discovery process and returns a channel from which new
	// Tasks can be read.
	Start(ctx context.Context, targets []string) (<-chan Task, error)
	// Stop gracefully terminates the discovery process.
	Stop()
}

DiscoveryEngine is responsible for discovering new tasks from a set of initial targets. It could be a web crawler, a file system scanner, or any other mechanism that identifies units of work.

type Edge

type Edge struct {
	ID         string           `json:"id"`
	From       string           `json:"from"` // The ID of the source node.
	To         string           `json:"to"`   // The ID of the target node.
	Type       RelationshipType `json:"type"`
	Label      string           `json:"label"`
	Properties json.RawMessage  `json:"properties"`
	CreatedAt  time.Time        `json:"created_at"`
	LastSeen   time.Time        `json:"last_seen"`
}

Edge represents a directed, typed, and labeled relationship between two nodes in the Knowledge Graph. It connects a 'from' node to a 'to' node and can have its own set of properties.

type EdgeInput

type EdgeInput struct {
	ID         string           `json:"id"`
	From       string           `json:"from"`
	To         string           `json:"to"`
	Type       RelationshipType `json:"type"`
	Label      string           `json:"label"`
	Properties json.RawMessage  `json:"properties"`
}

EdgeInput is a data structure used for efficiently adding or updating edges in bulk. It defines a relationship between two nodes.

type ElementGeometry

type ElementGeometry struct {
	Vertices []float64 `json:"vertices"` // The coordinates of the element's corners.
	Width    int64     `json:"width"`    // The width of the element in pixels.
	Height   int64     `json:"height"`   // The height of the element in pixels.
	// TagName provides the HTML tag of the element (e.g., "INPUT", "BUTTON"),
	// which can be used to influence interaction behavior.
	TagName string `json:"tagName"`
	// Type attribute of the element (e.g., "text", "password", "checkbox"),
	// further specializing interaction logic.
	Type string `json:"type,omitempty"`
}

ElementGeometry describes the physical properties of a DOM element on the page, including its dimensions, vertices, and tag information. This is used for precise, human-like interactions.

type Entry

type Entry struct {
	Pageref         string    `json:"pageref"`         // A reference to the page this entry belongs to.
	StartedDateTime time.Time `json:"startedDateTime"` // The timestamp when the request started.
	Time            float64   `json:"time"`            // The total time for the request-response cycle.
	Request         Request   `json:"request"`         // Detailed information about the HTTP request.
	Response        Response  `json:"response"`        // Detailed information about the HTTP response.
	Cache           struct{}  `json:"cache"`           // Information about the browser cache state.
	Timings         Timings   `json:"timings"`         // Detailed breakdown of the request timing phases.
}

Entry represents a single HTTP request-response pair recorded in the HAR.

type Event

type Event interface {
	// contains filtered or unexported methods
}

Event is a marker interface for event types. It is used to create a sum type of events that can be passed to the javascript package.

type FetchRequest

type FetchRequest struct {
	URL         string   `json:"url"`         // The URL of the request.
	Method      string   `json:"method"`      // The HTTP method (e.g., "GET", "POST").
	Headers     []NVPair `json:"headers"`     // The request headers.
	Body        []byte   `json:"body"`        // The request body.
	Credentials string   `json:"credentials"` // The credentials policy (e.g., "include", "omit").
}

FetchRequest encapsulates the details of an HTTP request made using the Fetch API from within the browser, including the URL, method, headers, and body.

type FetchResponse

type FetchResponse struct {
	URL        string   `json:"url"`        // The final URL after any redirects.
	Status     int      `json:"status"`     // The HTTP status code (e.g., 200, 404).
	StatusText string   `json:"statusText"` // The status text (e.g., "OK", "Not Found").
	Headers    []NVPair `json:"headers"`    // The response headers.
	Body       []byte   `json:"body"`       // The response body.
}

FetchResponse encapsulates the details of an HTTP response received from a Fetch API call, including the status code, headers, and response body.

type FileNodeProperties

type FileNodeProperties struct {
	FilePath string `json:"file_path"` // The full path to the file.
	Language string `json:"language"`  // The programming language of the file.
}

FileNodeProperties contains the specific attributes for a node of type NodeFile.

type Finding

type Finding struct {
	ID     string `json:"id"`      // Unique identifier for the finding.
	ScanID string `json:"scan_id"` // The ID of the scan that produced this finding.
	TaskID string `json:"task_id"` // The ID of the specific task that found this issue.

	// ObservedAt is the timestamp when the finding was discovered.
	ObservedAt time.Time `json:"observed_at"`

	Target string `json:"target"` // The target URL or resource where the vulnerability was found.
	Module string `json:"module"` // The name of the analysis module that reported the finding.

	// VulnerabilityName is a descriptive name for the type of vulnerability (e.g., "Reflected XSS").
	VulnerabilityName string `json:"vulnerability_name"`

	Severity    Severity `json:"severity"`    // The severity level of the finding.
	Description string   `json:"description"` // A detailed description of the vulnerability.

	// Evidence provides structured, machine-readable proof of the vulnerability,
	// stored as JSONB in the database.
	Evidence json.RawMessage `json:"evidence,omitempty"`

	Recommendation string   `json:"recommendation"` // Suggested steps for remediation.
	CWE            []string `json:"cwe,omitempty"`  // A list of relevant Common Weakness Enumeration (CWE) identifiers.
}

Finding encapsulates all the details of a single security vulnerability identified by a scan. It includes information about the vulnerability, its location, severity, and evidence. This struct maps directly to the `findings` table in the database.

type FunctionNodeProperties

type FunctionNodeProperties struct {
	StartLine  int  `json:"start_line"`  // The starting line number of the function in the file.
	EndLine    int  `json:"end_line"`    // The ending line number of the function.
	IsExported bool `json:"is_exported"` // Whether the function is exported for external use.
}

FunctionNodeProperties contains the specific attributes for a node of type NodeFunction.

type GenerationOptions

type GenerationOptions struct {
	Temperature     *float64 `json:"temperature"`       // Controls randomness. Lower is more deterministic.
	ForceJSONFormat bool     `json:"force_json_format"` // If true, forces the model to output valid JSON.
	TopP            float64  `json:"top_p"`             // Nucleus sampling parameter.
	TopK            int      `json:"top_k"`             // Top-k sampling parameter.
}

GenerationOptions provides detailed parameters to control the text generation process of the LLM, such as creativity (temperature) and output format.

type GenerationRequest

type GenerationRequest struct {
	SystemPrompt string            `json:"system_prompt"` // Instructions for the model's persona and task.
	UserPrompt   string            `json:"user_prompt"`   // The specific query or input from the user.
	Tier         ModelTier         `json:"tier"`          // The desired model tier (fast or powerful).
	Options      GenerationOptions `json:"options"`       // Advanced generation parameters.
}

GenerationRequest encapsulates a complete request to the LLM, including the system and user prompts, the desired model tier, and generation options.

type HAR

type HAR struct {
	Log HARLog `json:"log"`
}

HAR is the root object of the HTTP Archive format, which represents a log of HTTP requests and responses. See http://www.softwareishard.com/blog/har-1-2-spec/ for the full specification.

func NewHAR

func NewHAR() *HAR

NewHAR is a factory function that creates and initializes a new HAR object with default values for the log version and creator information.

type HARCookie

type HARCookie struct {
	Name     string `json:"name"`
	Value    string `json:"value"`
	Path     string `json:"path,omitempty"`
	Domain   string `json:"domain,omitempty"`
	Expires  string `json:"expires,omitempty"` // The expiration date in a string format.
	HTTPOnly bool   `json:"httpOnly,omitempty"`
	Secure   bool   `json:"secure,omitempty"`
}

HARCookie represents an HTTP cookie as defined in the HAR specification. It uses a string for the 'Expires' field to maintain strict conformance.

type HARLog

type HARLog struct {
	Version string  `json:"version"` // The version of the HAR format.
	Creator Creator `json:"creator"` // Information about the tool that created the HAR.
	Pages   []Page  `json:"pages"`   // A list of pages loaded during the session.
	Entries []Entry `json:"entries"` // A list of all recorded HTTP requests and responses.
}

HARLog is the main container within a HAR file, holding metadata about the creator, pages, and a list of all network entries.

type HTTPClient

type HTTPClient interface {
	// Get performs an HTTP GET request to the specified URL and returns the
	// response body, status code, and any error that occurred.
	Get(ctx context.Context, url string) (body []byte, statusCode int, err error)
}

HTTPClient provides a simple interface for making HTTP GET requests. It's used for basic network operations where the full power of a browser is not required.

type HistoryState

type HistoryState struct {
	State interface{} `json:"state"` // The serialized state object associated with the history entry.
	Title string      `json:"title"` // The title of the page at this history entry.
	URL   string      `json:"url"`   // The URL of the history entry.
}

HistoryState represents a single entry in the browser's navigation history, capturing the state, title, and URL at a specific point in time.

type HumanoidActionType

type HumanoidActionType string

HumanoidActionType defines the type of a single action within a human-like interaction sequence.

const (
	HumanoidMove     HumanoidActionType = "MOVE"      // Moves the mouse to a target.
	HumanoidClick    HumanoidActionType = "CLICK"     // Clicks the mouse.
	HumanoidDragDrop HumanoidActionType = "DRAG_DROP" // Drags an element from a start to an end point.
	HumanoidType     HumanoidActionType = "TYPE"      // Types text using the keyboard.
	HumanoidPause    HumanoidActionType = "PAUSE"     // Pauses for a human-like duration.
)

type HumanoidForceSource

type HumanoidForceSource struct {
	PositionX float64 `json:"position_x"` // The x-coordinate of the force's origin.
	PositionY float64 `json:"position_y"` // The y-coordinate of the force's origin.
	Strength  float64 `json:"strength"`   // The strength of the force (positive for attraction, negative for repulsion).
	Falloff   float64 `json:"falloff"`    // The rate at which the force's influence decays with distance.
}

HumanoidForceSource represents a point of attraction or repulsion in a potential field, used to create more realistic, curved mouse movement instead of straight lines.

type HumanoidInteractionOptions

type HumanoidInteractionOptions struct {
	// EnsureVisible, if true, will automatically scroll the element into view. Defaults to true.
	EnsureVisible *bool `json:"ensure_visible,omitempty"`
	// FieldSources defines a set of attractors/repulsors to create a potential field for mouse movement.
	FieldSources []HumanoidForceSource `json:"field_sources,omitempty"`
}

HumanoidInteractionOptions provides advanced configuration for a humanoid action, such as controlling automatic scrolling or defining a potential field to influence mouse trajectories.

type HumanoidSequenceParams

type HumanoidSequenceParams struct {
	Steps []HumanoidStep `json:"steps"`
	// Persona allows overriding the default browser fingerprint for this sequence,
	// enabling more flexible and realistic emulation.
	Persona *Persona `json:"persona,omitempty"`

	// --- ADDED FIELDS ---
	// TaintTemplate specifies which IAST taint tracking template to use (e.g., "strict", "permissive").
	TaintTemplate string `json:"taint_template,omitempty"`
	// TaintConfig allows passing a custom JSON configuration string for fine-grained control over taint sources and sinks.
	TaintConfig string `json:"taint_config,omitempty"`
}

HumanoidSequenceParams defines the complete set of parameters for a HUMANOID_SEQUENCE task, including the steps to execute and an optional custom browser persona.

type HumanoidStep

type HumanoidStep struct {
	Action      HumanoidActionType          `json:"action"`                  // The type of action to perform.
	Selector    string                      `json:"selector,omitempty"`      // The CSS selector for the target element.
	EndSelector string                      `json:"end_selector,omitempty"`  // For DragDrop actions, the destination selector.
	Text        string                      `json:"text,omitempty"`          // For Type actions, the text to be typed.
	MeanScale   float64                     `json:"mean_scale,omitempty"`    // For Pause actions, scales the mean pause duration.
	StdDevScale float64                     `json:"std_dev_scale,omitempty"` // For Pause actions, scales the standard deviation of the pause duration.
	Options     *HumanoidInteractionOptions `json:"options,omitempty"`       // Advanced options for this specific step.
}

HumanoidStep represents a single, discrete action in a sequence of human-like interactions.

type IDORTaskParams

type IDORTaskParams struct {
	HTTPMethod  string            `json:"http_method"`  // The HTTP method to use for the request.
	HTTPBody    string            `json:"http_body"`    // The request body.
	HTTPHeaders map[string]string `json:"http_headers"` // The request headers.
}

IDORTaskParams provides the parameters for an Insecure Direct Object Reference (IDOR) testing task.

type ImprovementAttemptProperties

type ImprovementAttemptProperties struct {
	GoalObjective string                 `json:"goal_objective"`       // The high-level goal being pursued.
	StrategyDesc  string                 `json:"strategy_description"` // The strategy devised to achieve the goal.
	ActionType    string                 `json:"action_type"`          // The specific type of action taken.
	ActionPayload map[string]interface{} `json:"action_payload"`       // The parameters and data used in the action.
	OutcomeOutput string                 `json:"outcome_output"`       // The result or output of the action.
}

ImprovementAttemptProperties contains the specific attributes for a node of type NodeImprovementAttempt, capturing the details of a self-healing or evolution action.

type InteractionAction

type InteractionAction string

InteractionAction represents a specific type of action that can be performed within a web browser, such as navigating to a URL, clicking an element, or typing text.

const (
	ActionNavigate InteractionAction = "navigate" // Navigates to a new URL.
	ActionClick    InteractionAction = "click"    // Clicks on a DOM element.
	ActionType     InteractionAction = "type"     // Types text into an input field.
	ActionSelect   InteractionAction = "select"   // Selects an option in a dropdown.
	ActionSubmit   InteractionAction = "submit"   // Submits a form.
	ActionWait     InteractionAction = "wait"     // Pauses for a specified duration.
	ActionScroll   InteractionAction = "scroll"   // Scrolls the page.
)

Constants defining the set of supported browser interaction actions.

type InteractionConfig

type InteractionConfig struct {
	MaxDepth                int               `json:"max_depth"`                   // Maximum depth for crawling links.
	MaxInteractionsPerDepth int               `json:"max_interactions_per_depth"`  // Max actions on a single page.
	InteractionDelayMs      int               `json:"interaction_delay_ms"`        // Delay between actions.
	PostInteractionWaitMs   int               `json:"post_interaction_wait_ms"`    // Wait time after an action for page load.
	CustomInputData         map[string]string `json:"custom_input_data,omitempty"` // Pre-filled data for forms.
	Steps                   []InteractionStep `json:"steps,omitempty"`             // A specific sequence of actions to perform.
}

InteractionConfig provides a comprehensive configuration for controlling automated browser interactions, including crawl depth, delays, and custom interaction sequences.

type InteractionStep

type InteractionStep struct {
	Action       InteractionAction `json:"action"`                 // The type of action to perform.
	Selector     string            `json:"selector,omitempty"`     // CSS selector for targeting a DOM element.
	Value        string            `json:"value,omitempty"`        // The value to use (e.g., text to type, option to select).
	Milliseconds int               `json:"milliseconds,omitempty"` // Duration for wait actions.
	Direction    string            `json:"direction,omitempty"`    // Direction for scroll actions (e.g., "down", "up").
}

InteractionStep represents a single, discrete action to be performed by the browser automation service. A sequence of these steps defines a user journey.

type JSFileTaskParams

type JSFileTaskParams struct {
	FilePath string `json:"file_path"`         // The path or URL of the JavaScript file.
	Content  string `json:"content,omitempty"` // The content of the file, if already available.
}

JSFileTaskParams provides the parameters for a JavaScript file analysis task.

type JWTTaskParams

type JWTTaskParams struct {
	Token string `json:"token"` // The JWT token to be analyzed.
}

JWTTaskParams provides the parameters for a JSON Web Token analysis task.

type KeyEventData

type KeyEventData struct {
	// Key represents the main key being pressed (e.g., "a", "Enter", "Tab").
	// The value should be compatible with the strings expected by the Chrome
	// DevTools Protocol's `input.dispatchKeyEvent` command.
	Key string
	// Modifiers is a bitmask representing the combination of active modifier keys.
	Modifiers KeyModifier
}

KeyEventData encapsulates the information for a single keyboard event, including the primary key that was pressed and any active modifier keys like Shift, Ctrl, or Alt.

type KeyModifier

type KeyModifier int

KeyModifier defines a bitmask for keyboard modifiers (Ctrl, Alt, Shift, Meta) to be used in keyboard events. The values are aligned with the Chrome DevTools Protocol's `input.DispatchKeyEvent` modifiers.

const (
	ModNone  KeyModifier = 0 // No modifiers are active.
	ModAlt   KeyModifier = 1 // The Alt key is active.
	ModCtrl  KeyModifier = 2 // The Ctrl key is active.
	ModMeta  KeyModifier = 4 // The Meta key (e.g., Command on Mac) is active.
	ModShift KeyModifier = 8 // The Shift key is active.
)

Constants for keyboard modifiers, designed to be combined using bitwise OR.

type KnowledgeGraphClient

type KnowledgeGraphClient interface {
	// AddNode adds a new node to the knowledge graph.
	AddNode(ctx context.Context, node Node) error
	// AddEdge adds a new edge between two nodes in the knowledge graph.
	AddEdge(ctx context.Context, edge Edge) error
	// GetNode retrieves a node by its unique ID.
	GetNode(ctx context.Context, id string) (Node, error)
	// GetEdge retrieves an edge by its unique ID.
	GetEdge(ctx context.Context, id string) (Edge, error)
	// GetEdges retrieves all edges connected to a specific node.
	GetEdges(ctx context.Context, nodeID string) ([]Edge, error)
	// GetNeighbors retrieves all nodes directly connected to a specific node.
	GetNeighbors(ctx context.Context, nodeID string) ([]Node, error)
	// QueryImprovementHistory searches for past self-improvement attempts related
	// to a specific objective.
	QueryImprovementHistory(ctx context.Context, goalObjective string, limit int) ([]Node, error)
}

KnowledgeGraphClient defines the standard interface for all interactions with the knowledge graph. It provides methods for adding, retrieving, and querying nodes and edges, abstracting the underlying graph database.

type KnowledgeGraphUpdate

type KnowledgeGraphUpdate struct {
	NodesToAdd []NodeInput `json:"nodes_to_add"`
	EdgesToAdd []EdgeInput `json:"edges_to_add"`
}

KnowledgeGraphUpdate serves as a container for a set of changes to be applied to the knowledge graph. It allows for batching node and edge additions into a single, atomic update.

type LLMClient

type LLMClient interface {
	// Generate produces a text completion based on the provided request.
	Generate(ctx context.Context, req GenerationRequest) (string, error)
	// Close cleans up any resources held by the client (e.g., network connections, SDK resources).
	Close() error
}

LLMClient defines a standard interface for interacting with a Large Language Model, abstracting the specifics of the underlying provider (e.g., Gemini).

type ModelTier

type ModelTier string

ModelTier allows for selecting a large language model based on a preference for speed versus advanced capabilities.

const (
	TierFast     ModelTier = "fast"     // Prefers a faster, potentially less capable model.
	TierPowerful ModelTier = "powerful" // Prefers a more capable, potentially slower model.
)

type MouseButton

type MouseButton string

MouseButton identifies a specific mouse button.

const (
	ButtonNone   MouseButton = "none"   // No button.
	ButtonLeft   MouseButton = "left"   // The left mouse button.
	ButtonRight  MouseButton = "right"  // The right mouse button.
	ButtonMiddle MouseButton = "middle" // The middle mouse button.
)

Constants for different mouse buttons.

type MouseEventData

type MouseEventData struct {
	Type       MouseEventType `json:"type"`       // The type of the mouse event.
	X          float64        `json:"x"`          // The x-coordinate of the event.
	Y          float64        `json:"y"`          // The y-coordinate of the event.
	Button     MouseButton    `json:"button"`     // The primary button associated with the event.
	Buttons    int64          `json:"buttons"`    // A bitmask of all buttons currently pressed.
	ClickCount int            `json:"clickCount"` // The number of consecutive clicks.
	DeltaX     float64        `json:"deltaX"`     // The horizontal scroll amount for wheel events.
	DeltaY     float64        `json:"deltaY"`     // The vertical scroll amount for wheel events.
}

MouseEventData encapsulates all the information related to a single mouse event, including its type, position, and button state.

type MouseEventType

type MouseEventType string

MouseEventType defines the specific type of a mouse event, such as movement, pressing a button, or releasing it.

const (
	MouseMove    MouseEventType = "mouseMoved"    // The mouse was moved.
	MousePress   MouseEventType = "mousePressed"  // A mouse button was pressed.
	MouseRelease MouseEventType = "mouseReleased" // A mouse button was released.
	MouseWheel   MouseEventType = "mouseWheel"    // The mouse wheel was scrolled.
)

Constants for different types of mouse events.

type NVPair

type NVPair struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

NVPair represents a simple name-value pair, used for headers, query strings, and form parameters.

type Node

type Node struct {
	ID         string          `json:"id"`
	Type       NodeType        `json:"type"`
	Label      string          `json:"label"`
	Status     NodeStatus      `json:"status"`
	Properties json.RawMessage `json:"properties"` // Flexible JSONB field for type-specific data.
	CreatedAt  time.Time       `json:"created_at"`
	LastSeen   time.Time       `json:"last_seen"`
}

Node represents a single entity or concept in the Knowledge Graph. Each node has a unique ID, a type, a label for display, and a set of properties that store detailed, structured information.

type NodeInput

type NodeInput struct {
	ID         string          `json:"id"`
	Type       NodeType        `json:"type"`
	Label      string          `json:"label"`
	Status     NodeStatus      `json:"status"`
	Properties json.RawMessage `json:"properties"`
}

NodeInput is a data structure used for efficiently adding or updating nodes in bulk. It contains all the necessary information to create a new node.

type NodeStatus

type NodeStatus string

NodeStatus tracks the lifecycle state of a node within the knowledge graph, often used to manage analysis workflows. The values are lowercase to match the corresponding ENUM in the PostgreSQL database.

const (
	StatusNew        NodeStatus = "new"        // The node has been discovered but not yet processed.
	StatusProcessing NodeStatus = "processing" // The node is currently being analyzed.
	StatusAnalyzed   NodeStatus = "analyzed"   // The node has been fully analyzed.
	StatusError      NodeStatus = "error"      // An error occurred during the analysis of the node.
	StatusSuccess    NodeStatus = "success"    // A process involving the node completed successfully.
	StatusFailure    NodeStatus = "failure"    // A process involving the node failed.
)

type NodeType

type NodeType string

NodeType represents the specific type of an entity (node) in the knowledge graph.

const (
	NodeHost               NodeType = "HOST"
	NodeIPAddress          NodeType = "IP_ADDRESS"
	NodeURL                NodeType = "URL"
	NodeCookie             NodeType = "COOKIE"
	NodeHeader             NodeType = "HEADER"
	NodeAccount            NodeType = "ACCOUNT"
	NodeTechnology         NodeType = "TECHNOLOGY"
	NodeVulnerability      NodeType = "VULNERABILITY"
	NodeAction             NodeType = "ACTION"
	NodeObservation        NodeType = "OBSERVATION"
	NodeTool               NodeType = "TOOL"
	NodeFile               NodeType = "FILE"
	NodeDomain             NodeType = "DOMAIN"
	NodeFunction           NodeType = "FUNCTION"
	NodeMission            NodeType = "MISSION"
	NodeImprovementAttempt NodeType = "IMPROVEMENT_ATTEMPT"
)

type OASTInteraction

type OASTInteraction struct {
	Canary          string    // The unique canary token that triggered the interaction.
	Protocol        string    // The protocol of the interaction (e.g., "HTTP", "DNS").
	SourceIP        string    // The IP address from which the interaction originated.
	InteractionTime time.Time // The timestamp of the interaction.
	RawRequest      string    // The raw request data, if available.
}

OASTInteraction represents a single interaction (e.g., an HTTP request or DNS lookup) received by the OAST server.

type OASTProvider

type OASTProvider interface {
	// GetInteractions queries the OAST server for any interactions that match a
	// given list of canary tokens.
	GetInteractions(ctx context.Context, canaries []string) ([]OASTInteraction, error)
	// GetServerURL returns the public URL of the OAST server, which can be used
	// in payloads.
	GetServerURL() string
}

OASTProvider defines the interface for an Out-of-Band Application Security Testing service. It provides a way to check for interactions with a public server initiated by the target application.

type ObservationType

type ObservationType string

ObservationType categorizes an observation made by an autonomous agent, providing context about what the information represents.

const (
	ObservationSystemState     ObservationType = "SYSTEM_STATE"     // An observation about the state of the system or environment.
	ObservationCodebaseContext ObservationType = "CODEBASE_CONTEXT" // An observation about the structure or content of the codebase.
	ObservationEvolutionResult ObservationType = "EVOLUTION_RESULT" // The result of a self-improvement or evolution attempt.
)

type Orchestrator

type Orchestrator interface {
	// StartScan initiates a new scan for a given set of targets and a unique scan ID.
	StartScan(ctx context.Context, targets []string, scanID string) error
}

Orchestrator coordinates the entire scan process, from discovery to task execution and result processing. It's the central component that ties the different engines together.

type Page

type Page struct {
	StartedDateTime time.Time   `json:"startedDateTime"` // The timestamp when the page load started.
	ID              string      `json:"id"`              // A unique identifier for the page.
	Title           string      `json:"title"`           // The title of the page.
	PageTimings     PageTimings `json:"pageTimings"`     // Timings for page load events.
}

Page represents a single page that was loaded in the browser. A HAR file can contain multiple pages if the user navigated during the recording session.

type PageTimings

type PageTimings struct {
	OnContentLoad float64 `json:"onContentLoad"` // Time until the DOMContentLoaded event, in milliseconds.
	OnLoad        float64 `json:"onLoad"`        // Time until the page's load event, in milliseconds.
}

PageTimings contains timing information for key page load events, such as DOMContentLoaded and the window's load event.

type Persona

type Persona struct {
	UserAgent       string       `json:"userAgent"`
	Platform        string       `json:"platform"`
	Languages       []string     `json:"languages"`
	Width           int64        `json:"width"`
	Height          int64        `json:"height"`
	AvailWidth      int64        `json:"availWidth"`
	AvailHeight     int64        `json:"availHeight"`
	ColorDepth      int64        `json:"colorDepth"`
	PixelDepth      int64        `json:"pixelDepth"`
	Mobile          bool         `json:"mobile"`
	Timezone        string       `json:"timezoneId"`
	Locale          string       `json:"locale"`
	ClientHintsData *ClientHints `json:"clientHintsData,omitempty"`
	// WebGLVendor and WebGLRenderer are used to spoof canvas fingerprinting attempts.
	WebGLVendor   string `json:"webGLVendor,omitempty"`
	WebGLRenderer string `json:"webGLRenderer,omitempty"`
	NoiseSeed     int64  `json:"noiseSeed"`
}

Persona defines a complete and consistent browser fingerprint for emulation. It includes everything from the User-Agent string and screen dimensions to WebGL details and locale settings, ensuring that the automated browser appears like a real user's environment.

type PostData

type PostData struct {
	MimeType string   `json:"mimeType"` // The MIME type of the posted data.
	Text     string   `json:"text"`     // The raw text of the posted data.
	Params   []NVPair `json:"params"`   // A list of parameters for form-encoded data.
}

PostData contains information about the data sent in an HTTP POST request.

type ProbeType

type ProbeType string

ProbeType categorizes the type of attack payload used in a taint analysis or active vulnerability check.

const (
	ProbeTypeXSS                ProbeType = "XSS"                 // Cross-Site Scripting probes.
	ProbeTypeSSTI               ProbeType = "SSTI"                // Server-Side Template Injection probes.
	ProbeTypeSQLi               ProbeType = "SQLI"                // SQL Injection probes.
	ProbeTypeCmdInjection       ProbeType = "CMD_INJECTION"       // Command Injection probes.
	ProbeTypeOAST               ProbeType = "OAST"                // Out-of-Band Application Security Testing probes.
	ProbeTypeDOMClobbering      ProbeType = "DOM_CLOBBERING"      // DOM Clobbering probes.
	ProbeTypePrototypePollution ProbeType = "PROTOTYPE_POLLUTION" // Prototype Pollution probes.
	ProbeTypeGeneric            ProbeType = "GENERIC"             // Generic or uncategorized probes.
)

Constants for different categories of attack probes.

type RaceConditionParams

type RaceConditionParams struct {
	Method  string              `json:"method"`
	Headers map[string][]string `json:"headers"`
	Body    []byte              `json:"body"`
}

RaceConditionParams defines parameters for the Race Condition task.

type RelationshipType

type RelationshipType string

RelationshipType defines the semantic type of a relationship (edge) between two nodes in the knowledge graph.

const (
	RelationshipResolvesTo     RelationshipType = "RESOLVES_TO"     // e.g., A HOST resolves to an IP_ADDRESS.
	RelationshipLinksTo        RelationshipType = "LINKS_TO"        // e.g., A URL links to another URL.
	RelationshipUses           RelationshipType = "USES"            // e.g., A HOST uses a TECHNOLOGY.
	RelationshipHas            RelationshipType = "HAS"             // e.g., A HOST has a COOKIE.
	RelationshipExposes        RelationshipType = "EXPOSES"         // e.g., A URL exposes a VULNERABILITY.
	RelationshipExecuted       RelationshipType = "EXECUTED"        // e.g., An AGENT executed a TOOL.
	RelationshipHasObservation RelationshipType = "HAS_OBSERVATION" // e.g., An ACTION has an OBSERVATION.
	RelationshipImports        RelationshipType = "IMPORTS"         // e.g., A FILE imports another FILE.
	RelationshipHostsURL       RelationshipType = "HOSTS_URL"       // e.g., A HOST hosts a URL.
	RelationshipHasSubdomain   RelationshipType = "HAS_SUBDOMAIN"   // e.g., A DOMAIN has a SUBDOMAIN.
	RelationshipAttempted      RelationshipType = "ATTEMPTED"       // e.g., A MISSION attempted an IMPROVEMENT_ATTEMPT.
)

type Request

type Request struct {
	Method      string      `json:"method"`
	URL         string      `json:"url"`
	HTTPVersion string      `json:"httpVersion"`
	Cookies     []HARCookie `json:"cookies"`
	Headers     []NVPair    `json:"headers"`
	QueryString []NVPair    `json:"queryString"`
	PostData    *PostData   `json:"postData,omitempty"`
	HeadersSize int64       `json:"headersSize"` // The size of the request headers in bytes.
	BodySize    int64       `json:"bodySize"`    // The size of the request body in bytes.
}

Request contains detailed information about a single HTTP request, including the method, URL, headers, and any posted data.

type Response

type Response struct {
	Status      int         `json:"status"`
	StatusText  string      `json:"statusText"`
	HTTPVersion string      `json:"httpVersion"`
	Cookies     []HARCookie `json:"cookies"`
	Headers     []NVPair    `json:"headers"`
	Content     Content     `json:"content"`
	RedirectURL string      `json:"redirectURL"`
	HeadersSize int64       `json:"headersSize"` // The size of the response headers in bytes.
	BodySize    int64       `json:"bodySize"`    // The size of the response body in bytes.
	// --- ADDED FIELDS ---
	// Custom fields for storing CDP network data for later analysis.
	// The underscore prefix indicates they are non-standard HAR fields.
	RemoteIPSpace   string `json:"_remoteIPAddressSpace,omitempty"` // The IP address space of the remote server.
	RemoteIPAddress string `json:"_remoteIPAddress,omitempty"`      // The IP address of the remote server.
}

Response contains detailed information about an HTTP response, including the status code, headers, and content. It also includes custom fields for storing additional network data from the Chrome DevTools Protocol.

type ResultEnvelope

type ResultEnvelope struct {
	ScanID    string                `json:"scan_id"`
	TaskID    string                `json:"task_id"`
	Timestamp time.Time             `json:"timestamp"`
	Findings  []Finding             `json:"findings"`
	KGUpdates *KnowledgeGraphUpdate `json:"kg_updates,omitempty"`
}

ResultEnvelope serves as the top-level container for the output of a single analysis task. It includes metadata like scan and task IDs, a timestamp, a list of all findings, and any updates to be made to the knowledge graph.

type SessionContext

type SessionContext interface {
	ID() string                                                                  // Returns the unique ID of the session.
	Navigate(ctx context.Context, url string) error                              // Navigates the session to a new URL.
	Click(ctx context.Context, selector string) error                            // Clicks on an element matching the selector.
	Type(ctx context.Context, selector string, text string) error                // Types text into an element.
	Submit(ctx context.Context, selector string) error                           // Submits a form.
	ScrollPage(ctx context.Context, direction string) error                      // Scrolls the page up or down.
	WaitForAsync(ctx context.Context, milliseconds int) error                    // Waits for a specified period.
	ExposeFunction(ctx context.Context, name string, function interface{}) error // Exposes a Go function to the browser's JS context.
	InjectScriptPersistently(ctx context.Context, script string) error           // Injects a script that persists across navigations.
	Interact(ctx context.Context, config InteractionConfig) error                // Executes a complex sequence of interactions.
	Close(ctx context.Context) error                                             // Closes the browser session.
	CollectArtifacts(ctx context.Context) (*Artifacts, error)                    // Gathers all available data (HAR, DOM, etc.).
	AddFinding(ctx context.Context, finding Finding) error                       // Reports a new finding discovered in this session.
	Sleep(ctx context.Context, d time.Duration) error                            // Pauses execution for a duration.
	DispatchMouseEvent(ctx context.Context, data MouseEventData) error           // Dispatches a low-level mouse event.
	SendKeys(ctx context.Context, keys string) error                             // Sends a sequence of keystrokes.
	// DispatchStructuredKey sends a key press event with modifiers (e.g., Ctrl+C).
	DispatchStructuredKey(ctx context.Context, data KeyEventData) error
	GetElementGeometry(ctx context.Context, selector string) (*ElementGeometry, error)             // Gets the geometry of an element.
	ExecuteScript(ctx context.Context, script string, args []interface{}) (json.RawMessage, error) // Executes a JavaScript snippet.
}

SessionContext defines the interface for controlling a single browser tab or session. It provides a rich set of methods for navigation, interaction, script execution, and artifact collection.

type Severity

type Severity string

Severity represents the severity level of a security finding, ranging from critical to informational. The values are lowercase to align with database ENUMs.

const (
	SeverityCritical Severity = "critical" // Represents a critical vulnerability.
	SeverityHigh     Severity = "high"     // Represents a high-severity vulnerability.
	SeverityMedium   Severity = "medium"   // Represents a medium-severity vulnerability.
	SeverityLow      Severity = "low"      // Represents a low-severity vulnerability.
	SeverityInfo     Severity = "info"     // Represents an informational finding.
)

Constants defining the standard severity levels for findings.

type StorageState

type StorageState struct {
	Cookies        []*Cookie         `json:"cookies"`
	LocalStorage   map[string]string `json:"local_storage"`
	SessionStorage map[string]string `json:"session_storage"`
}

StorageState provides a snapshot of the browser's storage for a given origin, including cookies, local storage, and session storage.

type Store

type Store interface {
	// PersistData saves a collection of findings and other results from a task
	// to the data store.
	PersistData(ctx context.Context, data *ResultEnvelope) error
	// GetFindingsByScanID retrieves all findings associated with a specific scan ID.
	GetFindingsByScanID(ctx context.Context, scanID string) ([]Finding, error)
}

Store defines a generic interface for a persistent storage system for scan data. This abstraction allows the application to be independent of the specific database implementation (e.g., PostgreSQL, in-memory).

type Subgraph

type Subgraph struct {
	Nodes []Node `json:"nodes"`
	Edges []Edge `json:"edges"`
}

Subgraph represents a subset of the full Knowledge Graph, containing a collection of nodes and the edges that connect them. It is often used to pass relevant context to different parts of the system.

type TaintSink

type TaintSink string

TaintSink represents a function, property, or location where tainted data could cause a security vulnerability if it is used without proper sanitization.

const (
	SinkEval                TaintSink = "EVAL"                          // eval()
	SinkFunctionConstructor TaintSink = "FUNCTION_CONSTRUCTOR"          // new Function()
	SinkSetTimeout          TaintSink = "SET_TIMEOUT"                   // setTimeout()
	SinkSetInterval         TaintSink = "SET_INTERVAL"                  // setInterval()
	SinkEventHandler        TaintSink = "EVENT_HANDLER"                 // on* event handlers (e.g., onclick).
	SinkInnerHTML           TaintSink = "INNER_HTML"                    // element.innerHTML
	SinkOuterHTML           TaintSink = "OUTER_HTML"                    // element.outerHTML
	SinkInsertAdjacentHTML  TaintSink = "INSERT_ADJACENT_HTML"          // element.insertAdjacentHTML
	SinkDocumentWrite       TaintSink = "DOCUMENT_WRITE"                // document.write()
	SinkScriptSrc           TaintSink = "SCRIPT_SRC"                    // script.src
	SinkIframeSrc           TaintSink = "IFRAME_SRC"                    // iframe.src
	SinkIframeSrcDoc        TaintSink = "IFRAME_SRCDOC"                 // iframe.srcdoc
	SinkWorkerSrc           TaintSink = "WORKER_SRC"                    // new Worker()
	SinkEmbedSrc            TaintSink = "EMBED_SRC"                     // embed.src
	SinkObjectData          TaintSink = "OBJECT_DATA"                   // object.data
	SinkBaseHref            TaintSink = "BASE_HREF"                     // base.href
	SinkNavigation          TaintSink = "NAVIGATION"                    // window.location, etc.
	SinkFetch               TaintSink = "FETCH_BODY"                    // fetch() body
	SinkFetchURL            TaintSink = "FETCH_URL"                     // fetch() URL
	SinkXMLHTTPRequest      TaintSink = "XHR_BODY"                      // XMLHttpRequest.send() body
	SinkXMLHTTPRequestURL   TaintSink = "XHR_URL"                       // XMLHttpRequest.open() URL
	SinkWebSocketSend       TaintSink = "WEBSOCKET_SEND"                // WebSocket.send()
	SinkSendBeacon          TaintSink = "SEND_BEACON"                   // navigator.sendBeacon()
	SinkPostMessage         TaintSink = "POST_MESSAGE"                  // window.postMessage()
	SinkWorkerPostMessage   TaintSink = "WORKER_POST_MESSAGE"           // worker.postMessage()
	SinkStyleCSS            TaintSink = "STYLE_CSS"                     // style.textContent, etc.
	SinkStyleInsertRule     TaintSink = "STYLE_INSERT_RULE"             // style.insertRule()
	SinkExecution           TaintSink = "EXECUTION_PROOF"               // Confirmed JavaScript execution.
	SinkOASTInteraction     TaintSink = "OAST_INTERACTION"              // Confirmed out-of-band interaction.
	SinkPrototypePollution  TaintSink = "PROTOTYPE_POLLUTION_CONFIRMED" // Confirmed prototype pollution.
)

Constants for various sinks where tainted data can lead to vulnerabilities.

type TaintSource

type TaintSource string

TaintSource identifies the origin of untrusted or "tainted" data that is introduced into the application.

const (
	SourceCookie         TaintSource = "COOKIE"          // Data from document.cookie.
	SourceLocalStorage   TaintSource = "LOCAL_STORAGE"   // Data from window.localStorage.
	SourceSessionStorage TaintSource = "SESSION_STORAGE" // Data from window.sessionStorage.
	SourceURLParam       TaintSource = "URL_PARAM"       // Data from URL query parameters.
	SourceHashFragment   TaintSource = "HASH_FRAGMENT"   // Data from the URL hash fragment.
	SourceReferer        TaintSource = "REFERER"         // Data from the Referer header.
	SourceHeader         TaintSource = "HEADER"          // Data from other HTTP headers.
	SourceDOMInput       TaintSource = "DOM_INPUT"       // Data from user input fields.
	SourceDOM            TaintSource = "DOM"             // Data from other DOM elements.
	SourceWebSocket      TaintSource = "WEB_SOCKET"      // Data from a WebSocket message.
	SourcePostMessage    TaintSource = "POST_MESSAGE"    // Data from a postMessage event.
)

Constants for various sources of tainted data in a web application.

type Task

type Task struct {
	TaskID     string      `json:"task_id"`    // A unique identifier for this specific task instance.
	ScanID     string      `json:"scan_id"`    // The ID of the parent scan this task belongs to.
	Type       TaskType    `json:"type"`       // The type of the task, which determines which worker will handle it.
	TargetURL  string      `json:"target_url"` // The primary URL or resource target for the task.
	Parameters interface{} `json:"parameters"` // A flexible field for task-specific parameters.
}

Task represents a single, self-contained unit of work to be processed by a worker in the task engine. It includes a unique ID, the type of task, the target, and any specific parameters required for its execution.

type TaskEngine

type TaskEngine interface {
	// Start begins processing tasks from the provided channel.
	Start(ctx context.Context, taskChan <-chan Task)
	// Stop gracefully terminates the task execution engine.
	Stop()
}

TaskEngine is responsible for executing a stream of tasks. It manages a pool of workers to process tasks concurrently.

type TaskType

type TaskType string

TaskType is an enumeration of the different types of analysis tasks that can be performed by the scanning engine.

const (
	TaskAgentMission        TaskType = "AGENT_MISSION"          // A high-level mission for the autonomous agent.
	TaskAnalyzeWebPageTaint TaskType = "ANALYZE_WEB_PAGE_TAINT" // Performs taint analysis on a web page.
	TaskTestRaceCondition   TaskType = "TEST_RACE_CONDITION"    // Tests for race conditions in web applications.
	TaskTestAuthATO         TaskType = "TEST_AUTH_ATO"          // Tests for account takeover vulnerabilities.
	TaskTestAuthIDOR        TaskType = "TEST_AUTH_IDOR"         // Tests for Insecure Direct Object References.
	TaskAnalyzeHeaders      TaskType = "ANALYZE_HEADERS"        // Analyzes HTTP security headers.
	TaskAnalyzeJWT          TaskType = "ANALYZE_JWT"            // Analyzes JSON Web Tokens for vulnerabilities.
	TaskAnalyzeJSFile       TaskType = "ANALYZE_JS_FILE"        // Performs static analysis on a JavaScript file.
	TaskHumanoidSequence    TaskType = "HUMANOID_SEQUENCE"      // Executes a sequence of human-like browser interactions.
)

type Timings

type Timings struct {
	Blocked float64 `json:"blocked"` // Time spent blocked before the request could be sent.
	DNS     float64 `json:"dns"`     // DNS lookup time.
	Connect float64 `json:"connect"` // TCP connection time.
	SSL     float64 `json:"ssl"`     // SSL/TLS handshake time.
	Send    float64 `json:"send"`    // Time spent sending the HTTP request.
	Wait    float64 `json:"wait"`    // Time spent waiting for the first byte of the response (TTFB).
	Receive float64 `json:"receive"` // Time spent receiving the response data.
}

Timings provides a detailed breakdown of the time spent in various phases of a single network request, from being blocked to receiving the final response.

type UserAgentBrandVersion

type UserAgentBrandVersion struct {
	Brand   string `json:"brand"`
	Version string `json:"version"`
}

UserAgentBrandVersion provides a structured representation of a brand in the User-Agent string, such as "Google Chrome" or "Not;A=Brand".

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL