analyzer

Documentation

Overview

Package analyzer coordinates TLS version scans and policy evaluation for one target.

It is the reusable core behind the command-line interface. The package keeps progress reporting optional through hooks so callers can build CLI, batch or library workflows on top of the same scan orchestration.

Callers can start with DefaultOptions and then override the fields they need:

opts := analyzer.DefaultOptions("example.com")
opts.MinVersion = tls.VersionTLS12
result, err := analyzer.Run(opts, analyzer.Hooks{})

Run returns scan evidence even when a target does not support a requested TLS version. It only returns an error for caller hook failures; operational scan failures are represented in Result.Results with scan statuses such as network_error, timeout and handshake_error.

Index

• Constants
• func RunFailed(results []scan.TLSScanResult) bool
• type HookError
  • func (e *HookError) Error() string
  • func (e *HookError) Unwrap() error
• type HookStage
• type Hooks
• type Options
  • func DefaultOptions(host string) Options
• type Result
  • func Run(opts Options, hooks Hooks) (Result, error)

Examples

• DefaultOptions
• Run

Constants

const (
	// DefaultPort is used when Options.Port is empty.
	DefaultPort = "443"
	// DefaultTimeout is used when Options.Timeout is zero.
	DefaultTimeout = 5 * time.Second
	// DefaultMinVersion is used when Options.MinVersion is zero.
	//
	// TLS 1.0 is intentional: the analyzer is a scanner and must be able to
	// detect and report legacy protocol support on the target. It does not
	// mean TLS 1.0 is recommended for clients or servers; use a policy (for
	// example --policy modern) to fail on legacy versions.
	DefaultMinVersion = tls.VersionTLS10
)

Functions

func RunFailed

func RunFailed(results []scan.TLSScanResult) bool

RunFailed reports whether the run produced only operational scan errors.

Types

type HookError

type HookError struct {
	Stage   HookStage
	Version string
	Err     error
}

HookError wraps errors returned by caller-provided hooks.

func (*HookError) Error

func (e *HookError) Error() string

func (*HookError) Unwrap

func (e *HookError) Unwrap() error

type HookStage

type HookStage string

HookStage identifies the callback that failed.

const (
	// HookStageSupported identifies errors returned by Hooks.Supported.
	HookStageSupported HookStage = "supported"
)

type Hooks

type Hooks struct {
	VersionStart func(versionName string, version uint16, probeCiphers bool)
	Unsupported  func(result scan.TLSScanResult)
	Supported    func(result scan.TLSScanResult, negotiatedCipher string) error
}

Hooks lets callers observe scan progress without coupling core analysis to UI output.

type Options

type Options struct {
	Host         string
	Port         string
	ServerName   string
	Timeout      time.Duration
	MinVersion   uint16
	ForceCiphers bool
	SkipVerify   bool
	PolicyConfig policy.Config
	Now          time.Time
}

Options configures one TLS analysis run for a single target.

func DefaultOptions

func DefaultOptions(host string) Options

DefaultOptions returns a single-target configuration matching CLI defaults.

Example

package main

import (
	"crypto/tls"

	"github.com/olelbis/tlsanalyzer/analyzer"
	"github.com/olelbis/tlsanalyzer/policy"
)

func main() {
	opts := analyzer.DefaultOptions("example.com")
	opts.ServerName = "example.com"
	opts.MinVersion = tls.VersionTLS12
	opts.PolicyConfig = policy.Config{Name: policy.NameModern}

	_ = opts
}

type Result

type Result struct {
	Results []scan.TLSScanResult
	Policy  policy.Result
}

Result contains scan evidence and the evaluated policy result.

func Run

func Run(opts Options, hooks Hooks) (Result, error)

Run executes the TLS scan matrix and evaluates the configured policy.

Example

package main

import (
	"crypto/tls"
	"errors"
	"fmt"
	"time"

	"github.com/olelbis/tlsanalyzer/analyzer"
)

func main() {
	opts := analyzer.DefaultOptions("example.com")
	opts.Timeout = 3 * time.Second
	opts.MinVersion = tls.VersionTLS12

	result, err := analyzer.Run(opts, analyzer.Hooks{
		VersionStart: func(versionName string, _ uint16, _ bool) {
			fmt.Printf("trying %s\n", versionName)
		},
	})
	if err != nil {
		var hookErr *analyzer.HookError
		if errors.As(err, &hookErr) {
			fmt.Printf("hook failed at %s\n", hookErr.Stage)
			return
		}
		fmt.Println(err)
		return
	}
	fmt.Println(len(result.Results))
}