Configuration Reference¶

The compatibility standards for shipped defaults, config sync and overrides are in Standards.

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 findings contribute their declared weight (0 by default) like any other finding; the FATAL signal is carried by the verdict label and the unsuppressible entry in score_breakdown, not by the number.

[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-P009, P004 skipped); 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]¶

[source_host_divergence]¶

config.toml is written once and read verbatim, so an install that predates this table keeps the shipped default (DEFAULT_SOURCE_DIVERGENCE_ALLOW in src/trustsight/config.py). The table is part of the configuration fingerprint: changing it changes which packages C011 reports, so two operators with different lists are different instruments.

[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 its signal rides the verdict label and the unsuppressible score_breakdown entry rather than the score, so an override changes nothing visible.

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 [code_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.

[code_rules]¶

Rules emitted from code rather than rules.toml, so the experimental flag above cannot reach them. They are not experimental: 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 (_CODE_RULE_DEFAULTS in src/trustsight/analysis/base.py). Setting a key here always overrides them.

This table was named [experimental_rules] before the rename. The old name is still read as a fallback, with a deprecation warning, so an existing config.toml keeps the rules it turned on or off; rename it to [code_rules].

[seed]¶

[release]¶

The baseline release channel TrustSight follows for its signed seed and corpus baselines. The official channel (emiliano-go/trustsight) is the default and is verified against the distribution key pinned in the package. Pointing this at another repository makes that publisher's key the trust anchor, so a non-official import warns every time and a channel with no configured key is refused rather than verified against the official key.

[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) from the newest ioc-* release (the dedicated IOC channel), verifies both against the pinned distribution key, then imports with the curator-key check the normal ioc import path performs. Any other http(s) url is read as a publisher's federation directory (manifest.json + iocs.jsonl) and verified against the feed's own pinned key; a feed with no key is refused, and a non-http(s) url is refused with an explicit error. The import is the same curator-key-checked ioc import path in every case.

[baselines.watchlist]¶

The imported watchlist. A signed watchlist-* release carries public package names and salted maintainer hashes (never plaintext); trustsight watchlist update downloads watchlist-official.json (plus its detached signature) from the newest watchlist-* release, verifies it against the pinned distribution key, and imports it. The imported set is stored in the database and unioned with the operator's hand-curated file at load, so a release import never clobbers a local entry.

Maintainer hashes are handled exactly as a baseline seed's: the release records the salt they were built under, and an import adopts it when the database has none. When a different salt is already stored, the maintainer hashes are skipped (they would be unreachable in the local namespace) while the package names still import.

[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.

[notify]¶

[notify]
webhook = "https://example.invalid/hooks/aur"

Where full-aur --watch pushes new alert clusters. With webhook set, a cycle that produced new alerts POSTs one JSON document (the cycle counts plus the package/rule_id pairs) to the URL; a quiet cycle sends nothing. Any receiver that accepts a JSON POST works, and ntfy shows the document as the message text. A dead receiver is logged and swallowed: a notification must never kill the watch loop. Overridden per run by --notify.

[alerts]¶

[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).

[verify]¶

[layers]¶

Override a rule's evidence category (its "layer"). The category names the kind of evidence the rule's findings represent, L1 (structural coherence) to L8 (campaign correlation). The shipped per-series default and per-rule overrides apply unless a rule id is named here.

[layers]
H099 = "L1"

Each entry maps a rule id to L1-L8. A value outside that range is ignored (the set is closed), as is a rule id this build does not ship. The security gate layer overrides stay within the closed set pins that.

[contacts]¶

The ledger itself lives in the database, append-only and versioned by cycle; [thresholds] g010 sets the shared-first-seen-host plurality floor. Neither contributes to the score.

[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 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¶

A malformed threshold value (a non-numeric string, null, or a list where a number is expected) falls back to the shipped default instead of aborting a corpus cycle. Counts are clamped to at least one, and a never-negative window or length is clamped to zero.

The E-series thresholds (e001/e002/e003) ship empty by design: the series is silent until a threshold is set from the first corpus measurement (scripts/entropy_calibrate.py prints conservative floors in the calibration CI job). The g003, g008, g009, g010 and t006 tables ship in thresholds.toml. The older G keys (g_host, g_blob, g_adopt), the T keys (t_key, t_dom), m002 and cofire_pairs are honoured if you add them, with the code defaults in the table above.

iocs.toml¶

[meta] version plus [[entries]] of type (package, domain, hash, file_path or pkgbuild_pattern), 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 sixteen environment variables. Everything else that changes behaviour is a config key or a command flag.

Rich output is the default only when the target stream is a terminal: renderers look at stdout, and progress bars look at stderr. A pipe, a redirect or a captured stream therefore gets plain text with no escape sequences. If NO_COLOR and FORCE_COLOR are both set, FORCE_COLOR wins.

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.