urlscan

README

urlscan

Submit URLs to urlscan.io and retrieve scan results, for the gollem LLM agent framework.

github.com/gollem-dev/tools/urlscan

Tools

Name	Description
urlscan_scan	Scan a URL with urlscan.io to analyse its content and behaviour.

The tool submits the URL, then polls for the finished result, honouring WithBackoff between polls and giving up after WithTimeout.

Usage

ts, err := urlscan.New("your-api-key")
if err != nil {
	return err
}
if err := ts.Ping(ctx); err != nil { // optional preflight
	return err
}

Options

Option	Default
WithBaseURL(string)	https://urlscan.io/api/v1
WithHTTPClient(*http.Client)	http.DefaultClient
WithBackoff(time.Duration)	3s
WithTimeout(time.Duration)	30s
WithLogger(*slog.Logger)	slog.Default()

Testing

Mock tests run unconditionally. The live-service test runs only when TEST_URLSCAN_API_KEY is set:

TEST_URLSCAN_API_KEY=... go test ./...

Documentation

Overview

Package urlscan provides a gollem.ToolSet for scanning URLs via urlscan.io.

Index

• type Option
  • func WithBackoff(d time.Duration) Option
  • func WithBaseURL(baseURL string) Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithLogger(logger *slog.Logger) Option
  • func WithTimeout(d time.Duration) Option
• type ToolSet
  • func New(apiKey string, opts ...Option) (*ToolSet, error)
  • func (t *ToolSet) Ping(ctx context.Context) error
  • func (t *ToolSet) Run(ctx context.Context, name string, args map[string]any) (map[string]any, error)
  • func (t *ToolSet) Specs(_ context.Context) ([]gollem.ToolSpec, error)

Types

type Option

type Option func(*ToolSet)

Option configures a ToolSet.

func WithBackoff

func WithBackoff(d time.Duration) Option

WithBackoff sets the interval between poll attempts while waiting for a scan result to become available. Default is 3 seconds.

func WithBaseURL

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the urlscan.io API base URL.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient overrides the HTTP client used for requests.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger sets the logger. A nil logger keeps the default (slog.Default()).

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the maximum time to wait for a scan result. Default is 30 seconds.

type ToolSet

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

ToolSet implements gollem.ToolSet for urlscan.io. Fields are unexported; configure via Option.

func New

func New(apiKey string, opts ...Option) (*ToolSet, error)

New constructs the ToolSet. It only validates static configuration; use Ping to verify connectivity and credentials.

func (*ToolSet) Ping

func (t *ToolSet) Ping(ctx context.Context) error

Ping verifies connectivity and credentials by performing a minimal authenticated GET against the API root. Any non-5xx response is treated as reachable; only network errors and server-side failures are considered fatal.

func (*ToolSet) Run

func (t *ToolSet) Run(ctx context.Context, name string, args map[string]any) (map[string]any, error)

Run executes the named urlscan tool.

func (*ToolSet) Specs

func (t *ToolSet) Specs(_ context.Context) ([]gollem.ToolSpec, error)

Specs returns the urlscan tool specifications.