Documentation
¶
Overview ¶
Package app is the application bootstrap. The Run entry point loads configuration, opens the infrastructure connections (PostgreSQL, Redis, NATS, PKI), then hands off to a mode-specific startup path. Mode startup is split across init_*.go files via the phased initContext pipeline so adding a new module is a localized change rather than another insertion into a 2,700-line function.
Index ¶
- Variables
- func ApplyLocalServicesTLS(cfg *Config)
- func GetVersionInfo() map[string]string
- func PrintVersion() error
- func ResetAdminPassword(cfgFile, newPassword string) error
- func Run(cfgFile, mode string) error
- func RunMigrations(cfgFile, action string) error
- func VersionString() string
- type AgentConfig
- type Application
- type CaddyConfig
- type Config
- type DatabaseConfig
- type DockerConfig
- type EgressProxyConfig
- type GuacdConfig
- type ImageBuilderConfig
- type ImageSignConfig
- type LoggingConfig
- type MetricsConfig
- type MinIOConfig
- type NATSConfig
- type NPMConfig
- type NginxConfig
- type ObservabilityConfig
- type ReconConfig
- type ReconConnectorToggle
- type ReconConnectorsConfig
- type ReconEgressConfig
- type ReconEngineConfig
- type RedisConfig
- type S3Config
- type SecurityConfig
- type ServerConfig
- type ServerTLSConfig
- type StorageConfig
- type TerminalConfig
- type TracingConfig
- type TrivyConfig
Constants ¶
This section is empty.
Variables ¶
var ( Version = "dev" Commit = "unknown" BuildTime = "unknown" )
Version information - set via ldflags at build time
Functions ¶
func ApplyLocalServicesTLS ¶
func ApplyLocalServicesTLS(cfg *Config)
ApplyLocalServicesTLS rewrites the in-cluster Postgres / Redis / NATS connection settings to use TLS when server.tls.local_services is true. When false (the default) the function is a no-op and the binary continues to speak plain TCP on the private docker network.
The rewrites match the docker-compose entrypoint behavior (deploy/tls/*.sh):
- Postgres: append `sslmode=require` to the URL when no sslmode is already present, and force Database.SSLMode to "require". Self- signed certs are accepted (`sslmode=require` does not verify the chain).
- Redis: rewrite the scheme from `redis://` to `rediss://` so the go-redis ParseURL sets up a TLS dialer. TLSSkipVerify is enabled so the self-signed leaf is accepted; operators can mount their own CA and set redis.tls_skip_verify=false to verify-full.
- NATS: enable NATS.TLS with SkipVerify=true. The URL itself stays `nats://` — nats.go switches to TLS via the client TLSConfig, not by URL scheme.
Explicit operator overrides take precedence: if Database.SSLMode is already set, the URL already includes sslmode=, the Redis URL is already rediss://, or NATS.TLS.Enabled is already true, the relevant branch is skipped. This keeps the helper idempotent and lets operators tighten the posture (verify-full, mTLS) without the shortcut clobbering their config.
func GetVersionInfo ¶
GetVersionInfo returns version information as a map
func PrintVersion ¶
func PrintVersion() error
PrintVersion prints version information to stdout. It returns an error so callers using cobra.Command.RunE can propagate failures to the root error handler; the current implementation writes to os.Stdout via fmt.Printf, which never returns an error in practice, but the typed return future-proofs the contract against a writer that does.
func ResetAdminPassword ¶
ResetAdminPassword resets the admin user password or creates the admin if missing.
func RunMigrations ¶
RunMigrations runs database migrations.
Types ¶
type AgentConfig ¶
type AgentConfig struct {
MasterURL string `mapstructure:"master_url"`
ID string `mapstructure:"id"`
Name string `mapstructure:"name"`
Token string `mapstructure:"token"`
HeartbeatInterval time.Duration `mapstructure:"heartbeat_interval"`
InventoryInterval time.Duration `mapstructure:"inventory_interval"`
MetricsInterval time.Duration `mapstructure:"metrics_interval"`
ReconnectDelay time.Duration `mapstructure:"reconnect_delay"`
MaxReconnectDelay time.Duration `mapstructure:"max_reconnect_delay"`
// TLS for NATS connection to master
TLSEnabled bool `mapstructure:"tls_enabled"`
TLSCertFile string `mapstructure:"tls_cert_file"`
TLSKeyFile string `mapstructure:"tls_key_file"`
TLSCAFile string `mapstructure:"tls_ca_file"`
}
AgentConfig holds agent-specific configuration
type Application ¶
type Application struct {
Config *Config
Logger *logger.Logger
DB *postgres.DB
Redis *redis.Client
NATS *nats.Client
Server *api.Server
// contains filtered or unexported fields
}
Application holds the long-lived dependencies that are constructed in Run and consumed by the phased init pipeline. Fields wired by an init_*.go phase live on the initContext (defined in init_context.go) unless they also require graceful shutdown.
type CaddyConfig ¶
type CaddyConfig struct {
Enabled bool `mapstructure:"enabled"`
AdminURL string `mapstructure:"admin_url"`
ACMEEmail string `mapstructure:"acme_email"`
ListenHTTP string `mapstructure:"listen_http"`
ListenHTTPS string `mapstructure:"listen_https"`
}
CaddyConfig holds Caddy reverse proxy configuration. Users connect their existing Caddy instance via the Settings UI.
type Config ¶
type Config struct {
Mode string `mapstructure:"mode"`
Server ServerConfig `mapstructure:"server"`
Database DatabaseConfig `mapstructure:"database"`
Redis RedisConfig `mapstructure:"redis"`
NATS NATSConfig `mapstructure:"nats"`
Security SecurityConfig `mapstructure:"security"`
Storage StorageConfig `mapstructure:"storage"`
Agent AgentConfig `mapstructure:"agent"`
Docker DockerConfig `mapstructure:"docker"`
Trivy TrivyConfig `mapstructure:"trivy"`
NPM NPMConfig `mapstructure:"npm"`
Caddy CaddyConfig `mapstructure:"caddy"`
Nginx NginxConfig `mapstructure:"nginx"`
Minio MinIOConfig `mapstructure:"minio"`
Logging LoggingConfig `mapstructure:"logging"`
Metrics MetricsConfig `mapstructure:"metrics"`
Observability ObservabilityConfig `mapstructure:"observability"`
Terminal TerminalConfig `mapstructure:"terminal"`
Guacd GuacdConfig `mapstructure:"guacd"`
Recon ReconConfig `mapstructure:"recon"`
ImageBuilder ImageBuilderConfig `mapstructure:"image_builder"`
ImageSign ImageSignConfig `mapstructure:"image_sign"`
EgressProxy EgressProxyConfig `mapstructure:"egress_proxy"`
}
Config holds all application configuration
func LoadConfig ¶
LoadConfig loads configuration from file and environment
func (*Config) EffectiveDatabaseURL ¶
EffectiveDatabaseURL returns Database.URL with sslmode appended from Database.SSLMode when the URL does not already carry an sslmode= query parameter. The original URL is returned untouched when SSLMode is empty or the URL already specifies one. Used by the application Run path and the standalone migrate / admin commands so both observe the same effective DSN.
func (*Config) PrintMasked ¶
func (c *Config) PrintMasked()
PrintMasked prints configuration with sensitive values masked
type DatabaseConfig ¶
type DatabaseConfig struct {
URL string `mapstructure:"url"`
SSLMode string `mapstructure:"ssl_mode"` // disable, allow, prefer, require, verify-ca, verify-full
MaxOpenConns int `mapstructure:"max_open_conns"`
MaxIdleConns int `mapstructure:"max_idle_conns"`
ConnMaxLifetime time.Duration `mapstructure:"conn_max_lifetime"`
ConnMaxIdleTime time.Duration `mapstructure:"conn_max_idle_time"`
QueryTimeout time.Duration `mapstructure:"query_timeout"`
}
DatabaseConfig holds PostgreSQL configuration
type DockerConfig ¶
type DockerConfig struct {
// Socket is the path to the Docker daemon Unix socket.
// For rootless Docker, this is typically /run/user/<UID>/docker.sock
// or $XDG_RUNTIME_DIR/docker.sock.
Socket string `mapstructure:"socket"`
}
DockerConfig holds Docker daemon connection configuration.
type EgressProxyConfig ¶
type EgressProxyConfig struct {
// Enabled gates both the proxy listener and the web UI. When false
// the egress service is unwired and /egress renders an "unavailable"
// page.
Enabled bool `mapstructure:"enabled"`
// ListenAddr is the TCP address the proxy binds. Defaults to ":18080"
// inside the egress package when blank. Common alternatives:
// "127.0.0.1:18080" (local-only) or "0.0.0.0:8888" (replace tinyproxy).
ListenAddr string `mapstructure:"listen_addr"`
}
EgressProxyConfig holds runtime knobs for the v26.5.2 L7 egress filter. The proxy listens on ListenAddr; workloads route HTTP_PROXY / HTTPS_PROXY at it; the service evaluates each request against the operator's per-host policies. Disabled by default — operators opt in because the proxy binds a TCP port on the host.
type GuacdConfig ¶
type GuacdConfig struct {
Enabled bool `mapstructure:"enabled"`
Host string `mapstructure:"host"`
Port int `mapstructure:"port"`
}
GuacdConfig holds Apache Guacamole daemon configuration for web-based RDP. The guacd service is included by default. Set GUACD_ENABLED=false to disable.
type ImageBuilderConfig ¶
type ImageBuilderConfig struct {
// MaxContextBytes caps a single build-context upload. Defaults to
// 256 MiB when zero or unset. Sized at the application layer so
// the cap is enforced before the payload reaches Docker.
MaxContextBytes int64 `mapstructure:"max_context_bytes"`
// LogTailBytes is the trailing window of build log bytes that is
// persisted to the row after a build completes. Defaults to 64 KiB.
LogTailBytes int `mapstructure:"log_tail_bytes"`
// LogChannelPrefix is the Redis pub/sub channel prefix used by
// the build streamer. Defaults to "imagebuilder:logs".
LogChannelPrefix string `mapstructure:"log_channel_prefix"`
}
ImageBuilderConfig holds runtime knobs for the image builder module. All fields default to sensible values via DefaultConfig() — operators only override when they need a larger context cap or a different log channel prefix.
type ImageSignConfig ¶
type ImageSignConfig struct {
Enabled bool `mapstructure:"enabled"`
}
ImageSignConfig toggles the optional cosign hook on successful builds. When Enabled is false the image builder skips the signing step. The actual cosign binary path / Sigstore endpoints live on the imagesign service config — this flag only controls the hook wiring.
type LoggingConfig ¶
type LoggingConfig struct {
Level string `mapstructure:"level"`
Format string `mapstructure:"format"`
Output string `mapstructure:"output"`
File struct {
Path string `mapstructure:"path"`
MaxSize string `mapstructure:"max_size"`
MaxBackups int `mapstructure:"max_backups"`
MaxAge int `mapstructure:"max_age"`
Compress bool `mapstructure:"compress"`
} `mapstructure:"file"`
}
LoggingConfig holds logging configuration
type MetricsConfig ¶
type MetricsConfig struct {
Enabled bool `mapstructure:"enabled"`
Path string `mapstructure:"path"`
GoMetrics bool `mapstructure:"go_metrics"`
ProcessMetrics bool `mapstructure:"process_metrics"`
}
MetricsConfig holds Prometheus metrics configuration
type MinIOConfig ¶
type MinIOConfig struct {
Enabled bool `mapstructure:"enabled"`
}
MinIOConfig holds MinIO/S3 configuration. S3 connections are managed manually via the Settings UI.
type NATSConfig ¶
type NATSConfig struct {
URL string `mapstructure:"url"`
Name string `mapstructure:"name"`
MaxReconnects int `mapstructure:"max_reconnects"`
ReconnectWait time.Duration `mapstructure:"reconnect_wait"`
JetStream struct {
Enabled bool `mapstructure:"enabled"`
Domain string `mapstructure:"domain"`
} `mapstructure:"jetstream"`
// Authentication
Token string `mapstructure:"token"`
Username string `mapstructure:"username"`
Password string `mapstructure:"password"`
// TLS Configuration
TLS struct {
Enabled bool `mapstructure:"enabled"`
CertFile string `mapstructure:"cert_file"`
KeyFile string `mapstructure:"key_file"`
CAFile string `mapstructure:"ca_file"`
SkipVerify bool `mapstructure:"skip_verify"`
} `mapstructure:"tls"`
}
NATSConfig holds NATS configuration
type NPMConfig ¶
type NPMConfig struct {
Enabled bool `mapstructure:"enabled"`
}
NPMConfig holds Nginx Proxy Manager integration configuration. NPM connections are managed manually via the Settings UI.
type NginxConfig ¶
type NginxConfig struct {
Enabled bool `mapstructure:"enabled"`
ConfigDir string `mapstructure:"config_dir"`
CertDir string `mapstructure:"cert_dir"`
ACMEEmail string `mapstructure:"acme_email"`
ACMEWebRoot string `mapstructure:"acme_web_root"`
ACMEAccountDir string `mapstructure:"acme_account_dir"`
ListenHTTP string `mapstructure:"listen_http"`
ListenHTTPS string `mapstructure:"listen_https"`
}
NginxConfig holds nginx reverse proxy configuration. When enabled, usulnet manages nginx configuration files and Let's Encrypt certificates directly. This is the default/recommended proxy backend.
type ObservabilityConfig ¶
type ObservabilityConfig struct {
Tracing TracingConfig `mapstructure:"tracing"`
}
ObservabilityConfig holds OpenTelemetry tracing and distributed observability settings.
type ReconConfig ¶
type ReconConfig struct {
// Enabled toggles the whole module. Default: false.
Enabled bool `mapstructure:"enabled"`
// RetentionDays controls how long findings and metadata artifacts
// survive before the retention worker sweeps them. Default: 90.
RetentionDays int `mapstructure:"retention_days"`
// MaxConcurrentScans caps how many recon scans the scheduler may
// run in parallel. Default: 2.
MaxConcurrentScans int `mapstructure:"max_concurrent_scans"`
// InstallationOrg is the organization name the RDAP-match ownership
// strategy compares against. Blank means "RDAP-based verification
// fails closed"; operators must set this explicitly to use the
// rdap_match method.
InstallationOrg string `mapstructure:"installation_org"`
// BaseURL overrides the public origin used to build email
// verification links. Falls back to Server.BaseURL when empty.
BaseURL string `mapstructure:"base_url"`
SpiderFoot ReconEngineConfig `mapstructure:"spiderfoot"`
Toolkit ReconEngineConfig `mapstructure:"toolkit"`
Egress ReconEgressConfig `mapstructure:"egress"`
Connectors ReconConnectorsConfig `mapstructure:"connectors"`
}
ReconConfig holds runtime knobs for the recon / privacy module. See docs/recon.md §13 and docs/v26.5/technical-notes.md "Feature flag".
Enabled gates the entire module: when false, none of the recon services, workers, network, or containers are constructed at runtime.
type ReconConnectorToggle ¶
type ReconConnectorToggle struct {
Enabled bool `mapstructure:"enabled"`
}
ReconConnectorToggle is the minimal enable/disable for a connector.
type ReconConnectorsConfig ¶
type ReconConnectorsConfig struct {
HIBP ReconConnectorToggle `mapstructure:"hibp"`
Shodan ReconConnectorToggle `mapstructure:"shodan"`
}
ReconConnectorsConfig toggles optional external-API connectors. The credentials themselves live in recon_connectors (encrypted) and are configured via the UI; these flags only control whether the connector is registered at startup.
type ReconEgressConfig ¶
type ReconEgressConfig struct {
Allowlist []string `mapstructure:"allowlist"`
}
ReconEgressConfig holds the egress allow-list applied at network creation. An empty list keeps the default policy (DNS + 80 + 443).
type ReconEngineConfig ¶
type ReconEngineConfig struct {
Image string `mapstructure:"image"`
Listen string `mapstructure:"listen"`
}
ReconEngineConfig is the per-engine image override (pin a digest in air-gapped installs or when CI publishes a new image).
type RedisConfig ¶
type RedisConfig struct {
URL string `mapstructure:"url"`
TLSEnabled bool `mapstructure:"tls_enabled"` // Force TLS even with redis:// URL
TLSCertFile string `mapstructure:"tls_cert_file"` // Client certificate for mTLS
TLSKeyFile string `mapstructure:"tls_key_file"` // Client key for mTLS
TLSCAFile string `mapstructure:"tls_ca_file"` // Custom CA for server verification
TLSSkipVerify bool `mapstructure:"tls_skip_verify"` // Skip server cert verification
PoolSize int `mapstructure:"pool_size"`
MinIdleConns int `mapstructure:"min_idle_conns"`
DialTimeout time.Duration `mapstructure:"dial_timeout"`
ReadTimeout time.Duration `mapstructure:"read_timeout"`
WriteTimeout time.Duration `mapstructure:"write_timeout"`
}
RedisConfig holds Redis configuration
type S3Config ¶
type S3Config struct {
Endpoint string `mapstructure:"endpoint"`
Bucket string `mapstructure:"bucket"`
Region string `mapstructure:"region"`
AccessKey string `mapstructure:"access_key"`
SecretKey string `mapstructure:"secret_key"`
UsePathStyle bool `mapstructure:"use_path_style"`
UseSSL bool `mapstructure:"use_ssl"` // Use HTTPS for S3 connections (default: true)
}
S3Config holds S3-compatible storage configuration
type SecurityConfig ¶
type SecurityConfig struct {
JWTSecret string `mapstructure:"jwt_secret"`
JWTExpiry time.Duration `mapstructure:"jwt_expiry"`
RefreshExpiry time.Duration `mapstructure:"refresh_expiry"`
ConfigEncryptionKey string `mapstructure:"config_encryption_key"`
CookieSecure bool `mapstructure:"cookie_secure"`
CookieSameSite string `mapstructure:"cookie_samesite"`
CookieDomain string `mapstructure:"cookie_domain"`
PasswordMinLength int `mapstructure:"password_min_length"`
PasswordRequireUpper bool `mapstructure:"password_require_uppercase"`
PasswordRequireNumber bool `mapstructure:"password_require_number"`
PasswordRequireSymbol bool `mapstructure:"password_require_special"`
MaxFailedLogins int `mapstructure:"max_failed_logins"`
LockoutDuration time.Duration `mapstructure:"lockout_duration"`
APIKeyLength int `mapstructure:"api_key_length"`
}
SecurityConfig holds security-related configuration
type ServerConfig ¶
type ServerConfig struct {
Host string `mapstructure:"host"`
Port int `mapstructure:"port"`
HTTPSPort int `mapstructure:"https_port"`
BaseURL string `mapstructure:"base_url"`
ReadTimeout time.Duration `mapstructure:"read_timeout"`
WriteTimeout time.Duration `mapstructure:"write_timeout"`
IdleTimeout time.Duration `mapstructure:"idle_timeout"`
ShutdownTimeout time.Duration `mapstructure:"shutdown_timeout"`
MaxRequestSize string `mapstructure:"max_request_size"`
RateLimitRPS int `mapstructure:"rate_limit_rps"`
RateLimitBurst int `mapstructure:"rate_limit_burst"`
RedirectHTTPS bool `mapstructure:"redirect_https"` // Redirect HTTP→HTTPS when TLS is enabled
// TLS configuration
TLS ServerTLSConfig `mapstructure:"tls"`
}
ServerConfig holds HTTP server configuration
type ServerTLSConfig ¶
type ServerTLSConfig struct {
// Enabled activates HTTPS. If true and no cert/key provided, auto-generates self-signed.
Enabled bool `mapstructure:"enabled"`
// CertFile is the path to a custom TLS certificate (overrides auto-generated)
CertFile string `mapstructure:"cert_file"`
// KeyFile is the path to a custom TLS private key
KeyFile string `mapstructure:"key_file"`
// AutoTLS generates a self-signed certificate if no custom cert is provided (default: true)
AutoTLS bool `mapstructure:"auto_tls"`
// DataDir is where auto-generated CA and certs are stored (default: <storage.path>/pki)
DataDir string `mapstructure:"data_dir"`
// LocalServices opts in to TLS for the in-cluster Postgres / Redis / NATS
// links. Defaults to false (plain TCP on the private docker network).
// When true, the compose entrypoints generate self-signed ECDSA P-256
// certs and the application rewrites the connection URLs to
// postgres ssl=require (skip-verify), rediss://, and nats with TLS.
// Operators can mount their own CA to flip skip-verify off.
LocalServices bool `mapstructure:"local_services"`
}
ServerTLSConfig holds TLS configuration for the HTTP server
type StorageConfig ¶
type StorageConfig struct {
Type string `mapstructure:"type"` // local | s3
Path string `mapstructure:"path"`
S3 S3Config `mapstructure:"s3"`
Backup struct {
Compression string `mapstructure:"compression"`
CompressionLevel int `mapstructure:"compression_level"`
RetentionDays int `mapstructure:"default_retention_days"`
} `mapstructure:"backup"`
}
StorageConfig holds storage configuration
type TerminalConfig ¶
type TerminalConfig struct {
Enabled bool `mapstructure:"enabled"`
User string `mapstructure:"user"`
Shell string `mapstructure:"shell"`
}
TerminalConfig holds host terminal configuration. Previously read from HOST_TERMINAL_* env vars; now centralized in Config.
type TracingConfig ¶
type TracingConfig struct {
// Enabled activates OpenTelemetry tracing. Default: false.
Enabled bool `mapstructure:"enabled"`
// Exporter selects the trace exporter: "otlp" (default).
Exporter string `mapstructure:"exporter"`
// Endpoint is the collector endpoint (e.g. "localhost:4318" for OTLP/HTTP).
Endpoint string `mapstructure:"endpoint"`
// Insecure disables TLS for the exporter connection. Default: true.
Insecure bool `mapstructure:"insecure"`
// SamplingRate controls the fraction of traces sampled (0.0–1.0). Default: 0.1.
SamplingRate float64 `mapstructure:"sampling_rate"`
}
TracingConfig holds distributed tracing configuration.
type TrivyConfig ¶
type TrivyConfig struct {
Enabled bool `mapstructure:"enabled"`
CacheDir string `mapstructure:"cache_dir"`
Timeout time.Duration `mapstructure:"timeout"`
Severity string `mapstructure:"severity"`
IgnoreUnfixed bool `mapstructure:"ignore_unfixed"`
UpdateDBOnStart bool `mapstructure:"update_db_on_start"`
}
TrivyConfig holds Trivy scanner configuration