Report Schema¶

The PackageFact dataclass (defined in src/trustsight/schema.py) is the core analysis result. It is serialised to JSON via fact_to_dict() (src/trustsight/schema.py) for database storage and for trustsight history --score-breakdown. The report bodies that review --json, inspect --json and the Python API's to_dict() emit are a different, shared shape, built by reporting.report_body: same keys on all three, with the score group withheld unless asked for. See B11.

JSON structure¶

{
  "package_name": "string",
  "old_version": "string",
  "new_version": "string",
  "old_commit": "string",
  "new_commit": "string",
  "maintainer_changed": bool,
  "previous_maintainer": "string",
  "current_maintainer": "string",
  "diff_summary": {
    "files_changed": ["string"],
    "file_changes": [{"path": "string", "status": "modified"}],
    "lines_added": int,
    "lines_removed": int
  },
  "source_changes": {
    "added_urls": ["string"],
    "removed_urls": ["string"],
    "checksum_behavior": "string"
  },
  "source_buckets": {"url": "bucket"},
  "execution_changes": {
    "resolved_commands": ["string"],
    "suspicious_patterns_detected": ["string"],
    "unresolved_patterns": ["string"]
  },
  "novelty_context": {
    "url_first_seen_in_this_package": bool,
    "url_first_seen_globally": bool,
    "maintainer_first_seen_for_this_package": bool
  },
  "score_breakdown": [
    {
      "rule_id": "string",
      "severity": "string",
      "weight": int,
      "reason": "string",
      "params": {},
      "template": "string",
      "evidence": {},
      "file": "string",
      "line": int
    }
  ],
  "first_seen": bool,
  "recent_commit_burst": bool,
  "diff_truncated": bool,
  "scan_truncated": bool,
  "tree_analyzed": bool,
  "config_fingerprint": "sha256:...",
  "changes": ["string"],
  "coverage_gaps": ["string"],
  "unresolved_sources": ["string"],
  "dependency_changes": {"field_name": ["name1", "name2"]},
  "dependencies": [
    {
      "name": "string",
      "depth": int,
      "score": int,
      "risk": "string",
      "risk_label": "string",
      "finding_count": int,
      "coverage_gaps": ["string"],
      "via": "string",
      "parent": "string",
      "failed": bool,
      "error": "string"
    }
  ],
  "risk": "string",
  "adapter": "string",
  "suppressed_rules": [
    {
      "rule_id": "string",
      "severity": "string",
      "override_reason": "string",
      "override_package": "string or null"
    }
  ],
  "ioc_matches": [
    {
      "type": "domain | hash | package",
      "value": "string",
      "source": "string",
      "confidence": "string",
      "provenance": "string",
      "campaign": "string",
      "added": "string",
      "surface": "string",
      "line": "int or null",
      "expired": bool
    }
  ],
  "final_score": int
}

Field descriptions¶

Top-level¶

diff_summary¶

Extracted by generate_diff() in src/trustsight/differ.py.

source_changes¶

source_buckets¶

Classified by classify_urls() in src/trustsight/buckets.py.

execution_changes¶

Resolution performed by tokenize_and_resolve() in src/trustsight/tokenizer.py.

novelty_context¶

Note: The NoveltyContext dataclass also carries observation_count (int), but this field is not serialised in fact_to_dict(). It is used internally by calculate_score() for the maturity multiplier.

Novelty built by build_novelty_context() in src/trustsight/novelty.py.

score_breakdown¶

Each entry:

The finding contract¶

Every rule emits a finding, never a judgement. A finding names a rule, a location, a template, and the evidence that satisfied it; the verdict layer renders from the template rather than from ad-hoc prose, which is what keeps the wording of a rule in one place. Neutral facts are reported the same way (new files, dependency additions, version bumps), at weight 0, so that "nothing scored" and "nothing happened" stay distinguishable.

The sum of all weight values, floored at 0 and capped at 100, equals final_score. FATAL rules short-circuit: if any entry has severity "FATAL", the score is 100 regardless of other entries.

Database storage¶

The PackageFact JSON is stored in the analysis_history table under the fact_json column (TEXT containing JSON). Triggered rules are stored in the separate triggered_rules table keyed by analysis_history.id. See insert_analysis() in src/trustsight/analysis/pipeline.py.

The two serializers¶

There are two JSON shapes, and they are not the same object.

• schema.fact_to_dict() produces the stored PackageFact, documented above. It is what goes into fact_json and into an exported baseline.
• The report body (trustsight review --json, trustsight inspect --json, and the Python API's Report.to_dict()) is a presentation view of the same analysis, built by reporting.report_body. All three surfaces return the same keys with the same values for the same result, which B11 requires and the the API and CLI emit the same JSON body gate enforces.

Always present (reporting.REPORT_KEYS): package, old_version, new_version, old_commit, new_commit, version_comparison, verdict, findings, file_changes, changes, coverage_gaps, suppressed_rules, ioc_matches, first_seen, is_trivial, diff_truncated, scan_truncated, failed, dependencies, depth_truncated, required_by, review_profile, review_threshold, flagged, config_fingerprint.

On request only:

Withholding the score withholds nothing else: the evidence keys are in the default body on every surface. A finding in the default body carries no weight - a weight is score arithmetic and travels with the breakdown.

dependencies is one entry per analysed AUR dependency, each with name, depth, score, risk, risk_label, finding_count, coverage_gaps, via, parent, failed and error. Each is a full analysis in its own right; a dependency's score is never folded into the parent's. See [depth]. depth_truncated says the walk stopped before the closure was exhausted, which also raises deps_not_scanned.

review_profile, review_threshold and flagged carry the review workload policy, not the risk assessment: flagged is true when the score is above the selected profile's threshold, and the profile and its effective threshold travel beside it so a consumer can see which queue produced the answer. They are in the default body while score is not, because whether something reached your queue is not the same claim as the number that put it there. See [review].

required_by is the reverse relationship: the packages in the reviewed set that declare this package as a dependency. It is populated by review --deps and TrustSight.review(deps=True), where the subject of the report is a dependency and the useful question is who needs it. Empty on an ordinary review, where the subject is the thing that was asked for - the key is always present so a consumer never has to special-case its absence.

ReviewResult.to_dict() and trustsight review --json serialize a list of these report bodies, not a wrapper object. A review can complete its command successfully while containing failed rows: those rows set failed to true and state that the package was not vetted. A consumer must check that field rather than treating an empty finding list as a clean result.

risk is the bare band ("Low", "Medium", "High", "Critical" or "Inconclusive"). It is a closed set: a FATAL finding does not add a member, it reports as Critical and names itself in risk_label (Critical (FATAL: R013)). A CRITICAL finding also floors the band at High regardless of the score, so risk is not a pure function of score - see the band rules. risk_label is the same band qualified for a person: a coverage gap appends (incomplete analysis) to an elevated band, and an Inconclusive names its cause: the gap(s) behind it, e.g. Inconclusive (diff truncated: payload may be hidden), or the cold start, e.g. Inconclusive (cold start: 22 more analyses needed). Machine consumers should gate on risk and coverage_gaps, not parse risk_label.

version_comparison is the one field worth knowing about by name. It records how the installed version relates to the AUR's declared pkgver, as one of aur_ahead, no_aur_change, installed_ahead or inconclusive. A VCS package computes its version at build time, so the two sides are frequently not comparable, and the outcome is stated rather than implied by an arrow. Machine consumers should read this field before treating old_version and new_version as an ordered pair.