checkscript

Documentation

Overview

Package checkscript runs user-authored passive scanner checks written in Starlark — a small, Python-like, deterministic language. It is the extension "standard": every custom check is a Starlark file that defines

def check(flow):
    # inspect flow, return a list of finding(...) (or [])

Starlark is sandboxed by design — a check cannot read files, open sockets, see the clock, or import anything we don't hand it — so checks are safe to share and run. Execution is additionally bounded (step limit) to stop runaway loops.

Index

• func Delete(dir, id string) error
• func Exists(dir, id string) bool
• func MergeDir(src, dst string) (int, error)
• func Read(dir, id string) (string, error)
• func Save(dir, id, src string) error
• func ValidID(id string) bool
• type Check
  • func Compile(id, src string) (*Check, error)
  • func LoadDir(dir string) ([]*Check, map[string]error)
  • func (c *Check) Run(f Flow) (issues []store.Issue, err error)
• type Flow
• type Source
  • func List(dir string) []Source

Functions

func Delete

func Delete(dir, id string) error

Delete removes a check.

func Exists

func Exists(dir, id string) bool

Exists reports whether <id>.star exists in dir.

func MergeDir

func MergeDir(src, dst string) (int, error)

MergeDir copies *.star files from src into dst without overwriting files already in dst. A missing src dir is not an error. Returns how many were copied.

func Read

func Read(dir, id string) (string, error)

Read returns one check's source.

func Save

func Save(dir, id, src string) error

Save validates that src compiles, then writes it as <id>.star (creating dir). A compile error is returned without writing, so a broken check never lands.

func ValidID

func ValidID(id string) bool

ValidID reports whether id is a safe check identifier.

Types

type Check

type Check struct {
	ID string
	// contains filtered or unexported fields
}

Check is a compiled Starlark check.

func Compile

func Compile(id, src string) (*Check, error)

Compile parses and compiles a check's source, validating that it defines a callable check(flow). The script's top level runs once here (sandboxed).

func LoadDir

func LoadDir(dir string) ([]*Check, map[string]error)

LoadDir compiles every `*.star` check in dir (sorted by name for determinism). It returns the compiled checks plus a filename→error map for any that failed to compile, so the caller can surface broken checks without aborting the rest. A missing directory yields no checks and no error.

func (*Check) Run

func (c *Check) Run(f Flow) (issues []store.Issue, err error)

Run executes the check against one flow and returns its findings. A runtime error (bad type, exceeded step limit, …) is returned, not panicked.

type Flow

type Flow struct {
	ID         int64
	Method     string
	Scheme     string
	Host       string
	Port       int
	Path       string
	Status     int
	Mime       string
	ReqHeaders map[string][]string
	ResHeaders map[string][]string
	ReqBody    string
	ResBody    string
}

Flow is the read-only view of a captured exchange handed to a check.

type Source

type Source struct {
	ID     string `json:"id"`
	Source string `json:"source"`
	Error  string `json:"error,omitempty"`
}

Source is a stored check: its id, raw source, and compile error (if any).

func List

func List(dir string) []Source

List returns every `*.star` check in dir (sorted), each with its source and a compile error if it currently fails to compile. A missing dir yields nil.