Add package documentation for pkg.go.dev directories view

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

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

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

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

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

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

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

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

internal/daemon/client.go

@@ -1,4 +1,3 @@
-// Package daemon provides a bounded HTTP client for the skeptic local daemon API.
 package daemon
 
 import (

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 (

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

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

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

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

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

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

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

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