Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
115 lines (86 loc) · 3.5 KB

CONTRIBUTING.md

File metadata and controls

115 lines (86 loc) · 3.5 KB
Raw

Contributing to ClawScan

Thanks for helping improve ClawScan. This repo is a Go CLI for agent-skill security scanning, so contributions should keep the public command general purpose, evidence-first, and safe to run in ordinary developer and CI environments.

Setup

Prerequisites:

  • Go 1.27.1 or newer (see go.mod).
  • Node.js/npm for scanner adapters that shell out through npx.
  • make for docs and release helper targets.
  • Optional scanner credentials in environment variables, never CLI flags.

From a checkout:

go test -count=1 ./...
go vet ./...
make docs-site
go run ./cmd/clawscan --help
go run ./cmd/clawscan ./README.md --scanner clawscan-static --json
node scripts/build-npm-package.mjs --version v0.0.0 --pack --smoke

Use fixture-backed scanner results when credentials or live upstream services are not available:

go run ./cmd/clawscan ./my-skill \
  --scanner skillspector \
  --scanner-result skillspector=./fixtures/skillspector.json \
  --json

What To Change

Keep pull requests focused on one behavior, adapter, documentation topic, or benchmark workflow. Avoid bundling scanner behavior, artifact schema changes, profile changes, and docs cleanup into one PR unless they are inseparable.

Public CLI flags must stay general purpose. ClawHub parity helpers can live in separate maintainer commands, but do not add ClawHub-specific flags to cmd/clawscan.

Good starting points:

Validation

For documentation-only changes, run:

make docs-site

For Go behavior, scanner adapters, profiles, artifacts, or help output, run:

go test -count=1 ./...
go vet ./...
go run ./cmd/clawscan --help

For npm package, wrapper, or release workflow changes, run:

node --test npm/clawscan/test/*.test.mjs
node --test scripts/build-npm-package.test.mjs
node scripts/build-npm-package.mjs --version v0.0.0 --pack --smoke

For Docker sandbox changes, also run the CLI integration test with Docker running:

go build ./cmd/clawscan
docker pull alpine:3.23
node --test scripts/docker-mounts.test.mjs

This checks plain paths and paths containing commas and quotes, including read-only targets and mounts and explicitly writable cache mounts. CI runs the same check. Set CLAWSCAN_BIN to test an existing binary instead.

For benchmark or leaderboard submission plumbing, CI validates changed submission directories. Maintainers can also run the repository validation script while debugging:

scripts/validate-security-signals-submissions.sh leaderboard/submissions/<run-id>

Commit And Review Expectations

  • Use conventional commit messages.
  • Keep generated dist/ changes out of ordinary feature and docs commits.
  • Mention the exact validation commands you ran in the PR or issue handoff.
  • Do not include secrets, tokens, or unredacted scanner output in commits, artifacts, issues, or pull requests.
  • Prefer small, reviewable changes with fixture-backed tests for scanner behavior.
  • For non-trivial changes, run python3 "$HOME/.agents/skills/autoreview/scripts/autoreview" --max-priority P3 before handoff.

Security Reports

Report vulnerabilities privately through this repository's GitHub private vulnerability reporting flow. See SECURITY.md for the full policy and what to include.