kernelguard 0.2.1

Rule-based GPU kernel hack detector.

KernelGuard

KernelGuard is a rule-based kernel hack detector for GPU-kernel competition submissions.

The core module is kernelguard.py, which can:

• classify a single submission from stdin
• scan JSONL pair datasets
• scan submission parquet exports
• generate a rule audit from a local review corpus
• load runtime config from built-in profiles, TOML files, and command-line overrides

Current Layout

• kernelguard.py Main detector and audit tool.

Install

pip install kernelguard

With extras:

pip install "kernelguard[parquet]"
pip install "kernelguard[mcp]"

uv

One-shot (no install):

uvx kernelguard --help
uvx kernelguard --api-mode < submission.py
uvx --from "kernelguard[parquet]" kernelguard --parquet submissions.parquet
uvx --from "kernelguard[mcp]" kernelguard-mcp --version

Permanent install:

uv tool install kernelguard                # core only
uv tool install "kernelguard[parquet]"     # + parquet scanning
uv tool install "kernelguard[mcp]"         # + MCP server
uv tool install "kernelguard[parquet,mcp]" # + parquet + MCP
uv tool install "kernelguard[api]"         # + HTTP API server

Entry points after installation: kernelguard, kguard, kernelguard-mcp, kguard-mcp, kernelguard-api, kguard-api.

Quick Start

Single kernel from stdin:

kernelguard --api-mode < submission.py

JSONL scan:

kernelguard --jsonl /path/to/pairs.jsonl --output-dir out/

Parquet scan:

kernelguard --parquet /path/to/submissions.parquet --output-dir out/

MCP Server

KernelGuard runs as a local MCP server over stdio.

kernelguard-mcp                  # default profile
kernelguard-mcp --profile strict # higher-recall review mode
kernelguard-mcp --version

Two tools:

• analyze_code — analyze a code string, return detection results.
• analyze_file — read a file path, return detection results plus resolved path.

Both accept optional metadata (for score-based detection) and profile parameters.

The server is read-only: no resources, prompts, scan tools, or write operations.

HTTP API Server

KernelGuard runs as an HTTP API server for integration with services like KernelBot.

kernelguard-api                           # default: 127.0.0.1:8088
kernelguard-api --host 0.0.0.0 --port 80 # public
kernelguard-api --profile strict          # higher-recall mode

Endpoints:

• GET /health — returns {"status": "ok", "version": "...", "profile": "..."}.
• POST /analyze — accepts {"code": "...", "metadata": null, "profile": "default"}, returns detection results.

The API server keeps KernelGuard loaded in memory, eliminating cold-start latency from subprocess invocations.

Runtime Config

The standalone repo already includes the later config-support additions from the newer line of development.

Runtime behavior can be controlled with:

• --profile Select a built-in profile.
• --config Load a TOML config file.
• --set Apply dotted key=value overrides from the CLI.
• --export-config Print or write the resolved config and exit.

Examples:

Export the default resolved config:

kernelguard --export-config

Export the strict profile:

kernelguard --profile strict --export-config

Run with a TOML config file:

kernelguard --config kernelguard.toml --jsonl /path/to/pairs.jsonl --output-dir out/

Apply a one-off override:

kernelguard --set 'entrypoints.names=["kernel"]' --api-mode < submission.py

The config layer covers:

• rule policy overrides
• score thresholds
• duplicate handling
• classification behavior
• entrypoint-name configuration

Compatibility

The primary public interfaces are:

• --api-mode for a single kernel
• --jsonl for pair datasets
• --parquet for submission exports

The detector also keeps some legacy compatibility for older internal audit/archive workflows so historical corpora can still be reused.

Audit Behavior

--audit-rules is meant to run in a workspace that contains the audit corpora and prior detector outputs.

This is an internal evaluation mode, not a normal first-run path.

If no audit fixtures are discovered, the command exits with a clear error instead of silently producing an empty audit report.

Minimal audit run:

kernelguard --audit-rules --output-dir audit_out/

If you want to drive audit mode from explicit inputs, put them in your config file:

[audit]
archive_dir = "/path/to/archive"
ground_truth_dir = "/path/to/ground_truth_dir"
manual_review_files = [
  "/path/to/manual_review_1.json",
  "/path/to/manual_review_2.json",
]
filtered_results_path = "/path/to/filtered_results.jsonl"

To compare old and new detector outputs explicitly during audit, put them in config too:

[audit.result_files]
old = "/path/to/old_results.jsonl"
new = "/path/to/new_results.jsonl"

Then run:

kernelguard --config kernelguard.toml --audit-rules --output-dir audit_out/

Generated audit artifacts include:

• classifier_fixture_manifest.json
• rule_audit_report.json
• rule_audit_report.md

Generated scan artifacts include:

• detection_results_*.jsonl
• detection_summary_*.json
• cleaned_pairs.jsonl

These generated files are ignored by the repo-level .gitignore.