Configuration Reference¶

File locations¶

All directories and default files are created on first run by ensure_default_configs() in src/trustsight/config.py.

config.toml¶

TOML file at ~/.config/trustsight/config.toml.

[severity_weights]¶

Map each severity level to its numeric contribution to the base score. FATAL rules short-circuit to score 100 regardless of weight.

[source_bucket_weights]¶

URLs in the diff are classified by classify_url() in src/trustsight/buckets.py.

[novelty_weights]¶

Raw weights for Tier C novelty signals. These are multiplied by the maturity multiplier (observation_count / 50, capped at 1.0) before being added to the score.

[review]¶

Controls the review workload, not score arithmetic or risk bands. A report is flagged when its score is above the selected profile's threshold. JSON records the profile, effective threshold, and flag; the configuration fingerprint covers the selected policy too.

[review]
profile = "quiet"

## Optional local changes to the three published workload choices.
[review.profiles]
quiet = 45

Only default, quiet, and strict are accepted. Thresholds must be integers from 0 through 100. Changing a profile does not change a score, risk band, or calibration result; it changes only the reports marked for review.

Removed: [verification_evidence] and [pinning_weights]¶

Both sections applied negative weights for declared checksums, PGP keys, GPG verification and source pinning. They are gone, and setting them in a local config.toml now does nothing.

Everything TrustSight sees is attacker-declared, and TrustSight never fetches, so it never confirms that a declared key signs anything or that a pinned commit holds what it claims. A signal an attacker can assert for free must not be able to lower a score. These facts are now reported as weight-0 declared-practice findings in the P namespace (P001-P008); see the security model.

Pinning classification via classify_pinning_level() in src/trustsight/buckets.py still runs; it decides which P finding is emitted, not a score.

[ports]¶

[domains]¶

[tools]¶

[rules]¶

[rules.R###]¶

Per-rule controls belong in config.toml, keyed by the rule ID:

[rules.R007]
enabled = false
weight_override = 15

enabled and weight_override apply only to rules defined in rules.toml, which since the R/H split means every R id and only those. They only have an effective scoring use for non-FATAL rules: a FATAL rule cannot be disabled and always hard-stops the score at 100.

An H rule is a heuristic emitted from an analysis module and has no TOML definition, so a [rules.H###] block does nothing. That is what the prefix is for - if you can name it with an R, you can configure it here. Use the documented dedicated settings for heuristics where available, such as [experimental_rules] below.

A [rules.R###] block naming an id this release retired (see the mapping) also does nothing, and did nothing before the rename either: those rules were always code-emitted. Retired ids are never reassigned, so such a block cannot later attach itself to an unrelated rule.

[experimental_rules]¶

Rules emitted from code rather than rules.toml, so the experimental flag above cannot reach them. All default to true, a value set by corpus calibration; see Fire Rates.

A config written before this section existed still gets these defaults: load_config() reads the file verbatim without merging defaults, so the fallbacks live in code (_EXPERIMENTAL_DEFAULTS in src/trustsight/analysis/base.py). Setting a key here always overrides them.

[seed]¶

[baselines]¶

Container for optional federated baseline sources. Currently only the IOC baseline stage is implemented. Baselines add attributed context; they never replace local structural detection or alter rules, weights, or thresholds.

[baselines.ioc]¶

[[baselines.ioc.feeds]]¶

Configured feed entries for trustsight ioc update. TrustSight ships with no default feeds; operators add trusted sources here. A feed whose url names the TrustSight release channel is updated automatically: ioc update downloads the pair baseline-ioc-<prefix>-manifest.json and baseline-ioc-<prefix>-iocs.jsonl (plus their detached signatures), verifies both against the pinned distribution key, then imports with the curator-key check the normal ioc import path performs. Any other url is refused with an explicit "not implemented" error; there is no scheme in which an unverified remote baseline is imported.

[depth]¶

[depth]
levels = 1

How far into a package's AUR dependency closure to analyse. 0 disables it, 1 (the default) analyses direct AUR dependencies, n analyses n levels, and -1 walks every level there is.

-1 is bounded, and it has to be: the dependency graph is written by the party under review, so an unbounded walk would let a crafted recipe decide how many repositories this machine clones. The ceilings are depth.MAX_DEPTH_LEVELS (8) and depth.MAX_DEPTH_NODES (200 dependencies per run), and a walk cut short by either records the deps_not_scanned coverage gap. A walk that completed is not a gap: asking for depth 1 and getting depth 1 answers the question that was asked.

Each dependency is analysed exactly as a package - its own score, its own band, its own row in the database. Nothing is folded into the parent's score, because depth is deliberately absent from the config fingerprint and a score that moved with --depth would break B1 for anyone comparing two runs.

Overridden per run by --depth.

[deep]¶

Deep analysis mode: reserved.

[diff]¶

[discovery]¶

Controls which packages are scanned when no --repo/--foreign/--all-repos flags are given on the command line. See CLI Reference for the full precedence rules.

If none of these settings are explicitly configured, the tool scans foreign packages only (backward-compatible default).

[limits]¶

The pattern and threshold files¶

config.toml holds weights and limits. The lists a rule matches against live in sibling files, so a rule can be retuned without touching code. Each is written on first run and never rewritten, so an edited file is always kept.

hosts.toml¶

For the overlapping settings, hosts.toml has precedence: standard_ports overrides [ports] standard, and free_registrar_tlds overrides [domains] free_registrar_tlds. An empty sibling list falls back to the corresponding config.toml value and then the shipped default. The other host lists are read directly by their named rules; they do not merge with a generic host setting.

patterns.toml¶

These lists are consumed directly by their named rules. network_tools is the exception with a legacy fallback: D003 reads patterns.toml first, then [tools] network_makedepends in config.toml, then the shipped default. There is no general precedence rule across sibling files.

naming.toml¶

Ecosystem prefixes (D004, H064) and variant suffixes (D002, H029, H052, H053). These decide when two package names belong to the same project, which is what keeps a package claiming its own project's names from firing a scope-expansion rule.

thresholds.toml¶

iocs.toml¶

[meta] version plus [[entries]] of type (package, domain or hash), value, confidence, provenance, campaign and added. The confidence tier decides severity: confirmed is FATAL, high is CRITICAL, medium is HIGH. The shipped file is empty, and a miss is uninformative.

Environment variables¶

TrustSight reads one environment variable. Everything else that changes behaviour is a config key or a command flag.

Every path that would reach the release channel checks it first, so an air-gapped machine or a CI runner is pinned to what is already on disk. The commands that need a channel refuse with a message naming the variable rather than failing as a transport error:

$ TRUSTSIGHT_OFFLINE=1 trustsight seed fetch
The release channel is disabled (TRUSTSIGHT_OFFLINE is set).

Four commands stop, and they do not all stop for the same reason:

It does not make the program offline. review and inspect still clone the package's own AUR repository, because that clone is how a diff exists at all; fetcher does not consult this variable. What the variable governs is the bulk and release channels, not the per-package fetch that A3 already constrains to one host keyed by package name. To stop all outbound traffic, deny it at the network layer.

Defined in release.offline().

Default configuration¶

The full default config is embedded in src/trustsight/config.py as DEFAULT_CONFIG and written to ~/.config/trustsight/config.toml on first invocation. Users may edit it freely.