From 51a6da385cacfd007113efff07379b82c5ac06f0 Mon Sep 17 00:00:00 2001 From: TGPSKI Date: Fri, 10 Apr 2026 10:21:36 -0700 Subject: [PATCH 1/2] Add package-level doc comments for all internal packages and module root - Create module-level doc.go for pkg.go.dev overview page - Add doc.go to 11 internal packages missing package documentation: rules, config, checks, scan, correlation, enrich, ingest, report, provenance, completion, mcp, corpus - Consolidate daemon package doc into doc.go (was duplicated across client.go and daemon.go with different descriptions) Closes #13 Made-with: Cursor --- doc.go | 27 +++++++++++++++++++++++++++ internal/checks/doc.go | 10 ++++++++++ internal/completion/doc.go | 3 +++ internal/config/doc.go | 11 +++++++++++ internal/corpus/doc.go | 7 +++++++ internal/correlation/doc.go | 9 +++++++++ internal/daemon/client.go | 1 - internal/daemon/daemon.go | 2 -- internal/daemon/doc.go | 9 +++++++++ internal/enrich/doc.go | 4 ++++ internal/ingest/doc.go | 5 +++++ internal/mcp/doc.go | 9 +++++++++ internal/provenance/doc.go | 5 +++++ internal/report/doc.go | 5 +++++ internal/rules/doc.go | 12 ++++++++++++ internal/scan/doc.go | 12 ++++++++++++ 16 files changed, 128 insertions(+), 3 deletions(-) create mode 100644 doc.go create mode 100644 internal/checks/doc.go create mode 100644 internal/completion/doc.go create mode 100644 internal/config/doc.go create mode 100644 internal/corpus/doc.go create mode 100644 internal/correlation/doc.go create mode 100644 internal/daemon/doc.go create mode 100644 internal/enrich/doc.go create mode 100644 internal/ingest/doc.go create mode 100644 internal/mcp/doc.go create mode 100644 internal/provenance/doc.go create mode 100644 internal/report/doc.go create mode 100644 internal/rules/doc.go create mode 100644 internal/scan/doc.go diff --git a/doc.go b/doc.go new file mode 100644 index 0000000..8f65799 --- /dev/null +++ b/doc.go @@ -0,0 +1,27 @@ +// Package skeptic is a standalone, stdlib-only Go security scanner that detects +// supply chain compromise, agentic/LLM ecosystem poisoning, CI/CD weaponization, +// and machine-identity abuse. It ships as a single static binary with zero +// runtime dependencies. +// +// skeptic targets structural trust boundary violations — the attack-enabling +// conditions that CVE scanners, SAST tools, and secret scanners do not cover: +// mutable action refs, unsafe pull_request_target patterns, MCP tool shadowing, +// over-permissioned service accounts, and similar misconfigurations. +// +// # Detection domains +// +// - CI/CD trust boundaries (CI-BUILD, CI-ENV, CI-PRT, CI-SECRET, CI-MUTABLE, ...) +// - Agentic ecosystem poisoning (AGT-SKL, AGT-MCP, AGT-MEM, AGT-OUT, AGT-TRUST, ...) +// - Persistence and stealer artifacts (ATK-*, DROP-*, OBF-*, ENC-*) +// - Machine identity abuse (GRAPH-*, MID-*, CLOUD-ID) +// - Supply chain structural hygiene (SCM-*, DEP-*, BHV-*) +// +// # Architecture +// +// The CLI entry point lives in [skeptic/cmd/skeptic]. Internal packages under +// [skeptic/internal] implement the scan engine, rule system, configuration, +// reporting, daemon, MCP server, threat-intel ingestion, and supporting +// infrastructure. All packages depend only on the Go standard library. +// +// See https://github.com/TGPSKI/skeptic for full documentation. +package skeptic diff --git a/internal/checks/doc.go b/internal/checks/doc.go new file mode 100644 index 0000000..f298170 --- /dev/null +++ b/internal/checks/doc.go @@ -0,0 +1,10 @@ +// Package checks implements behavioral, dependency, domain, focus, graph, and +// policy analysis passes that run alongside or after pattern matching. +// +// Behavior checks detect multi-step attack chains (ordered and unordered). +// Dependency checks analyze lockfiles and package manifests for supply chain +// indicators. Domain checks perform structural typosquat detection. Graph checks +// build identity graphs across AWS, Azure, GCP, and Kubernetes RBAC configs +// using BFS traversal. Focus checks apply file-type-specific heuristics. Policy +// checks enforce organizational governance rules. +package checks diff --git a/internal/completion/doc.go b/internal/completion/doc.go new file mode 100644 index 0000000..dfa3de4 --- /dev/null +++ b/internal/completion/doc.go @@ -0,0 +1,3 @@ +// Package completion generates shell completion scripts for bash, zsh, and fish. +// It produces completions for all skeptic subcommands and their flags. +package completion diff --git a/internal/config/doc.go b/internal/config/doc.go new file mode 100644 index 0000000..839e808 --- /dev/null +++ b/internal/config/doc.go @@ -0,0 +1,11 @@ +// Package config handles configuration file loading, preset resolution, profile +// management, and CLI flag registration for skeptic. +// +// Configuration sources are resolved in precedence order: mode defaults, preset +// overrides, config file values, and explicit CLI flags. Config files may be +// JSON, YAML, or .env format and are auto-discovered from the scan root or +// XDG config directories. +// +// The package also provides the init, config show, and config use subcommand +// implementations. +package config diff --git a/internal/corpus/doc.go b/internal/corpus/doc.go new file mode 100644 index 0000000..5704df9 --- /dev/null +++ b/internal/corpus/doc.go @@ -0,0 +1,7 @@ +// Package corpus manages an encrypted-at-rest collection of threat artifact +// files used for agentic rule validation and regression testing. +// +// Files are stored with AES-256-GCM encryption, tracked via a SHA256 manifest, +// and scanned in isolation to verify expected rule detections. The corpus +// supports init, fetch, info, scan (with --learn mode), and purge operations. +package corpus diff --git a/internal/correlation/doc.go b/internal/correlation/doc.go new file mode 100644 index 0000000..b94f92d --- /dev/null +++ b/internal/correlation/doc.go @@ -0,0 +1,9 @@ +// Package correlation performs cross-finding analysis after the primary scan +// completes, surfacing composite risk that individual findings cannot express. +// +// Correlation strategies include per-directory clustering, repo-level rollup, +// content-hash deduplication, file-basename grouping, and git-temporal analysis. +// Drift detection compares the current scan against a prior state file to +// identify new, removed, or changed findings. Correlated findings carry the +// COR-* and DRIFT-* rule ID prefixes. +package correlation diff --git a/internal/daemon/client.go b/internal/daemon/client.go index 0a009f9..21ebdc4 100644 --- a/internal/daemon/client.go +++ b/internal/daemon/client.go @@ -1,4 +1,3 @@ -// Package daemon provides a bounded HTTP client for the skeptic local daemon API. package daemon import ( diff --git a/internal/daemon/daemon.go b/internal/daemon/daemon.go index 4e23db3..41784de 100644 --- a/internal/daemon/daemon.go +++ b/internal/daemon/daemon.go @@ -1,5 +1,3 @@ -// Package daemon implements the skeptic HTTP daemon: scheduled scans, optional -// filesystem watch, health/status/report/metrics endpoints, and graceful shutdown. package daemon import ( diff --git a/internal/daemon/doc.go b/internal/daemon/doc.go new file mode 100644 index 0000000..4522e20 --- /dev/null +++ b/internal/daemon/doc.go @@ -0,0 +1,9 @@ +// Package daemon implements the skeptic HTTP daemon and its API client. +// +// The daemon provides scheduled background scans, optional filesystem watch, +// and a local HTTP API with health, status, report, metrics, and triggered-scan +// endpoints. It binds to loopback with token authentication by default. +// +// The client provides a bounded HTTP client for interacting with the daemon API +// from the MCP server and CLI subcommands. +package daemon diff --git a/internal/enrich/doc.go b/internal/enrich/doc.go new file mode 100644 index 0000000..2c4269a --- /dev/null +++ b/internal/enrich/doc.go @@ -0,0 +1,4 @@ +// Package enrich runs the post-scan enrichment pipeline, composing results from +// dependency checks, identity graph analysis, provenance verification, MCP +// discovery, drift detection, and git-temporal correlation into the final report. +package enrich diff --git a/internal/ingest/doc.go b/internal/ingest/doc.go new file mode 100644 index 0000000..08e9304 --- /dev/null +++ b/internal/ingest/doc.go @@ -0,0 +1,5 @@ +// Package ingest generates signed rule packs from external threat intelligence +// sources. It fetches content from URLs, files, and directories, applies format +// adapters (STIX, Sigma, YARA, URL-based advisories), and produces rule +// specifications that can be signed with Ed25519 and loaded by the scan engine. +package ingest diff --git a/internal/mcp/doc.go b/internal/mcp/doc.go new file mode 100644 index 0000000..0cf701e --- /dev/null +++ b/internal/mcp/doc.go @@ -0,0 +1,9 @@ +// Package mcp implements a JSON-RPC server that exposes skeptic functionality +// over the Model Context Protocol (MCP) via stdio. It provides tools for +// repository scanning, waiver creation, threat-intel ingestion, and daemon +// bridging. The server supports tool allowlisting, filesystem root restrictions, +// and optional auto-start of the local daemon. +// +// MCP config discovery scans standard editor and IDE configuration paths to +// detect existing MCP server registrations. +package mcp diff --git a/internal/provenance/doc.go b/internal/provenance/doc.go new file mode 100644 index 0000000..721145e --- /dev/null +++ b/internal/provenance/doc.go @@ -0,0 +1,5 @@ +// Package provenance verifies dependency provenance by comparing installed +// artifact hashes against expected values from lockfiles and SBOM documents. +// It supports SPDX and CycloneDX SBOM formats and cross-references package +// checksums to detect tampering or substitution. +package provenance diff --git a/internal/report/doc.go b/internal/report/doc.go new file mode 100644 index 0000000..d8c6bb2 --- /dev/null +++ b/internal/report/doc.go @@ -0,0 +1,5 @@ +// Package report formats scan results for output. Supported formats are plain +// text, JSON, SARIF, and Markdown. The package also implements baseline +// comparison for diff-only reporting, evidence export as signed tar.gz bundles, +// and distribution bundle packaging with integrity verification. +package report diff --git a/internal/rules/doc.go b/internal/rules/doc.go new file mode 100644 index 0000000..80d77d9 --- /dev/null +++ b/internal/rules/doc.go @@ -0,0 +1,12 @@ +// Package rules provides the built-in rule set, external rule pack loading, +// Ed25519 signature verification, and rule quality validation for skeptic. +// +// Rules are organized into group files by detection domain: agentic surfaces, +// attack tactics, behavioral signals, identity exposure, and non-code surfaces. +// Each rule is a [model.Rule] struct with an RE2-compatible pattern, severity, +// MITRE ATT&CK mapping, and file-type targeting. +// +// External rule packs are loaded from signed JSON files and merged with the +// built-in set at scan startup. The [BuildRuleSet] function composes the final +// rule slice from all sources. +package rules diff --git a/internal/scan/doc.go b/internal/scan/doc.go new file mode 100644 index 0000000..11f54f5 --- /dev/null +++ b/internal/scan/doc.go @@ -0,0 +1,12 @@ +// Package scan implements the core scan engine: file walking, worker pool +// dispatch, pattern matching, payload decoding, and result aggregation. +// +// The engine uses a configurable worker pool for concurrent file scanning, +// an incremental cache (mtime + size + SHA256) for skipping unchanged files, +// and an Aho-Corasick pre-filter for fast literal keyword elimination. +// +// Payload decoders (base64, hex, gzip, zlib, PowerShell, Unicode, and others) +// recursively decode embedded content with entropy-based bonus depth. Additional +// analysis includes Shannon entropy anomaly detection, NFKC normalization for +// homoglyph evasion, XOR brute-force decoding, and polyglot file detection. +package scan From ab193593ad87e92b40c04c70227d5d13b6ff877a Mon Sep 17 00:00:00 2001 From: TGPSKI Date: Fri, 10 Apr 2026 10:27:39 -0700 Subject: [PATCH 2/2] Fix CI trigger: run on opened events, keep ok-to-test gate for updates GITHUB_TOKEN API calls do not fire pull_request:labeled events, so the auto-label workflow adding ok-to-test never triggered CI. Fix by adding opened back to pull_request types and allowing opened events to bypass the label check (the PR author has push access). Fork PRs from untrusted users are still gated by ok-to-test on synchronize and labeled events. Made-with: Cursor --- .github/workflows/action-integration-test.yml | 3 ++- .github/workflows/ci.yml | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/workflows/action-integration-test.yml b/.github/workflows/action-integration-test.yml index a10a1d9..3565a8a 100644 --- a/.github/workflows/action-integration-test.yml +++ b/.github/workflows/action-integration-test.yml @@ -10,7 +10,7 @@ on: - 'internal/**' pull_request: branches: [main] - types: [synchronize, reopened, labeled] + types: [opened, synchronize, reopened, labeled] permissions: contents: read @@ -19,6 +19,7 @@ jobs: changes: if: >- github.event_name == 'push' || + github.event.action == 'opened' || contains(github.event.pull_request.labels.*.name, 'ok-to-test') runs-on: ubuntu-latest outputs: diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6df384b..a605097 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,7 +5,7 @@ on: branches: [main] pull_request: branches: [main] - types: [synchronize, reopened, labeled] + types: [opened, synchronize, reopened, labeled] permissions: contents: read @@ -14,6 +14,7 @@ jobs: test: if: >- github.event_name == 'push' || + github.event.action == 'opened' || contains(github.event.pull_request.labels.*.name, 'ok-to-test') strategy: matrix: