Skip to content

Latest commit

 

History

History
20 lines (18 loc) · 7.54 KB

AGENTS.md

File metadata and controls

20 lines (18 loc) · 7.54 KB

AGENTS.md

This file provides guidance to agents when working with code in this repository.

  • OwnAudit is the canonical audit repo (since 2026-07-18): the lift-out from Own.NET/audit/ happened and the direction reversed — Own.NET/audit/ is deprecated and Own.NET stays a pure SAST engine that emits findings. New aggregation/reporting/runtime/fix work lands here, not there. (Older docs in both repos may still state the pre-reversal boundary; docs/collector-plan.md is the current word.)
  • src/OwnAudit.Cli and src/OwnAudit.Runtime intentionally target net8.0-windows because runtime work depends on FlaUI/ClrMD; Linux work here is mainly the Python tooling/tests. OwnAudit.Runtime is the home of the ClrMD heap collector (docs/collector-plan.md).
  • Python tests are designed to run as bare scripts because pytest is not guaranteed in the dev shell: PYTHONUTF8=1 python3 arch/tests/test_arch.py or any */tests/test_*.py file directly.
  • Finding identity is a frozen contract, not a helper. identity/pattern.py implements finding-pattern/v1 and contracts/finding-pattern-v1.json holds its canonical vectors; viz/apply_verdicts.finding_id is an alias for it. Every stored fp-verdicts.json overlay is keyed by those exact bytes, so changing the algorithm, separator, truncation or field order orphans the verdicts — and the result is an empty report, not an error. Do not "clean up" the hash or normalize paths/messages. The SARIF partialFingerprints["ownAudit/v1"] is a different, legacy GitHub-correlation key (normalized message, full digest, /ordinal suffix) and must never be used as an identity.
  • Normalization is a ported stage with a byte-parity contract. aggregate/normalize.py + aggregate/sarif_read.py + aggregate/taxonomy/categories.json came from the deprecated Own.NET/audit/aggregate/ (Own.NET#266 slice 1A) and must keep producing byte-identical findings.json; aggregate/tests/fixtures/parity/expected-findings.json was generated by the reference implementation, so a diff there means the port drifted, not that the golden is stale. Set OWNNET_REF=/path/to/Own.NET to also re-derive the golden and re-verify the JSON taxonomy against the YAML it was transcribed from. The taxonomy is JSON, not YAML, because the Python tooling is stdlib-only — do not reintroduce a PyYAML dependency to read it. See docs/normalization.md.
  • Identity is refused, not approximated. identity/occurrence.py (finding-occurrence/v1) mints an occurrence_id only when the producer run, the producer, the pattern and an UNAMBIGUOUS physical anchor are all known; otherwise it emits null plus machine-readable identity_limitations. Its fields are LENGTH-PREFIXED, not separator-joined - a raw separator lets a control character shift between two fields and produce one preimage for two occurrences (the defect finding-pattern/v1 is frozen with); never "simplify" that back to a join. Never add an ordinal tiebreaker (it would make identity depend on SARIF emission order), never substitute a column the producer did not report (start_column is nullable on purpose - Own.NET's _caret_col is a renderer heuristic, not a coordinate), and never call a SARIF file digest a producer_run_id (that is input_digest, a provenance field). Run identity comes only from a producer-provenance/v1 manifest via --provenance; a digest mismatch is rejected with exit 2, not degraded, and a malformed manifest raises rather than being coerced. One --sarif input per producer name (provenance is keyed by producer, so two runs under one name cannot be represented) - it fails loudly. Run-Audit.ps1 vouches only for what it observed: pre-existing Infer#/Roslyn SARIF get producer_run_id: null and source_commit: null, a reused CodeQL DB gets source_commit: null, and a DIRTY target tree gets source_commit: null because the analyzers read the working tree rather than HEAD. See docs/finding-identity.md.
  • The payload is normalized-findings/v2: the ten frozen v1 fields plus four identity fields. The slice-1A parity golden is compared through project_v1 and is NEVER regenerated from the code under test - a failing projection means v2 changed something it promised only to add to.
  • Full Linux-safe regression sweep: PYTHONUTF8=1 python3 aggregate/tests/test_normalize.py && PYTHONUTF8=1 python3 identity/tests/test_occurrence.py && PYTHONUTF8=1 python3 arch/tests/test_arch.py && PYTHONUTF8=1 python3 fix/tests/test_orchestrate.py && PYTHONUTF8=1 python3 fix/tests/test_own_fix.py && PYTHONUTF8=1 python3 fix/tests/test_ai_fix.py && PYTHONUTF8=1 python3 leakmine/tests/test_leakmine.py && PYTHONUTF8=1 python3 report/tests/test_baseline.py && PYTHONUTF8=1 python3 report/tests/test_sarif.py && PYTHONUTF8=1 python3 report/tests/test_rules_map.py && PYTHONUTF8=1 python3 report/tests/test_annotate.py && PYTHONUTF8=1 python3 report/tests/test_exec.py && PYTHONUTF8=1 python3 viz/tests/test_dashboard_rules.py && PYTHONUTF8=1 python3 runtime/tests/test_runtime.py && PYTHONUTF8=1 python3 runtime/tests/test_member_aware.py && PYTHONUTF8=1 python3 oracle/fixtures/test_oracle_arch.py && PYTHONUTF8=1 python3 oracle/fixtures/test_oracle_runtime.py.
  • To run the collector against real STS documents, build the shipping stand first — docs/sts-stand-build.md (worktree build into Setup, SERIALIZERSIM_SETUP, leaktest --hold).
  • Run-Audit.ps1 is Windows-stand oriented and drives external Own.NET worktrees; it sets PYTHONUTF8=1, emits SARIF into artifacts/, and clusters optional Infer#/Roslyn results only if their SARIF files already exist.
  • Use Run-Audit.ps1 -Codeql for CodeQL corroboration. The clustering window is raised from 3 to 8 automatically when Infer# or Roslyn are folded in, because those tools report shifted/generated locations; the raise is announced on stdout. Passing -LineTol explicitly always wins — even a value below 8, which is warned about and then honoured, never silently corrected. The decision is Resolve-LineTol in scripts/LineTolPolicy.ps1, and its matrix is pinned by scripts/tests/Test-LineTolPolicy.ps1 on Windows and Linux.
  • Run-Infersharp.ps1 consumes built STS .dll + .pdb files via WSL and filters third-party/generated SARIF before Run-Audit.ps1 folds it.
  • Run-Roslyn.ps1 requires VS2022 BuildTools and injects analyzers with /p:OwnAudit=true; analyzer packs must stay in per-pack cache subdirs to avoid Gu.Roslyn.Extensions conflicts.
  • The three runners are pwsh-only, and say so where the engine can act on it. Run-Audit.ps1, Run-Infersharp.ps1 and Run-Roslyn.ps1 each open with #Requires -Version 7 and are kept byte-level ASCII (OwnAudit#64). The two go together: Windows PowerShell 5.1 reads a BOM-less file in the system ANSI codepage, so a single non-ASCII byte used to surface as a syntax error inside whatever word contained it - the requirement is unreachable if the file cannot be parsed to find it. The contract is NOT that the runners work under 5.1; it is that 5.1 can read them and refuse them for a true reason. Do not "fix" this with a BOM (it leaves the file non-ASCII and makes correctness depend on three bytes an editor may drop), and do not reintroduce typographic dashes into these files. scripts/tests/Test-RunnerShellContract.ps1 enforces it on both editions.
  • Generated/derived outputs live under artifacts/, arch/out/, report/out/, runtime/out/, and leakmine-out/; avoid treating them as source truth unless a test fixture explicitly depends on them.
  • .editorconfig has a project-specific C# gotcha: *.cs files use CRLF while JSON/YAML/Markdown/PowerShell use 2-space indentation.