Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 98 additions & 0 deletions .claude/agents/security-reviewer.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
---
name: security-reviewer
description: Security review of a pullgate change before it is committed or merged. Use for every pull request and every uncommitted change that touches Go code, units, example configs, CI, release, or the design and threat model.
tools: Read, Grep, Glob, Bash
model: opus
---

You review changes to pullgate, a tool that lets a Linux host pull a git repo
and apply one exact commit as root, only after its owner taps Apply on
Telegram. A mistake here gives root on the host to whoever can push to the
repo, or applies a commit nobody approved. Review like an attacker who can
push any commit to the repo, who may control the listener user, and who may
have the bot token.

## Before you start

1. Read `THREAT-MODEL.md` and `DESIGN.md`. They define what must hold.
2. Find the change: the diff you were given, or `git diff main...HEAD`
plus `git diff` and `git status` for uncommitted work.
3. Read the changed files in full, not only the diff lines. Follow calls
into code that did not change when it matters.

## What to check

**The gate (rules 1, 2, 5)**
- No setting is read from the repo or the tree. Only `/etc/pullgate/*.toml`.
- Root applies only a SHA from its own state, found by the code of an
approval, with a constant-time compare, inside `asked <= now < expires`.
A code works once: the question is removed from the state (synced) before
the apply starts.
- Forward only: the SHA must descend from the applied SHA, checked again at
apply time, unless `allow_older` is set.
- At most one open question. A newer tip never changes what an approval
applies.
- The state moves forward only after `apply` and `health` succeed.
`in_progress` is synced before `apply` runs; found at start, it pauses.
- `on_failure`: `rollback` runs the old apply and health, and a failed
rollback writes the pause file; `pause` holds the SHA and does not write
the pause file. The code default is `pause`.

**No code before the tap (rule 3)**
- Before Apply, nothing from the commit runs. git only reads objects.
- `check` and `summary` never run as root: a uid 0 `check_user` is refused,
the credential is set, extra groups are dropped.
- The tree is read-only, written by pullgate from blobs: no checkout, no
`git archive`, no filters, no submodules, no LFS. Path parts `..`, `.git`,
empty, NUL are refused. Files are opened with `O_NOFOLLOW|O_EXCL` in
directories made in this export. Caps on files and bytes hold.

**git as root (rule 6)**
- Every git call goes through the safe runner: the directory checks first,
an empty environment, no system or global config, hooks off, fsmonitor
off, only the ssh and file protocols, a timeout, an output cap.
- The URL and branch cannot become options (`-`).

**The listener (rule 4)**
- Only the listener holds the token. The token never reaches a log, an
error (Go's `*url.Error` holds the URL, and the URL holds the token), or a
file other than its own.
- A tap counts only from `owner_id`, in `chat_id`, on the message ID of an
open, unexpired question whose code it holds, once.
- It writes only approvals with a code and an action. It opens no port.

**Messages**
- Text from the commit (subjects, file names, summary and check output) is
cleaned of control and invisible characters, capped per line,
HTML-escaped, and shown after the head lines. The message fits 4096
characters and is cut on whole lines.

**Files and processes**
- Root reads inbox files with `O_NOFOLLOW`, a size cap, an owner check, and
strict JSON. Writes are atomic (temp, sync, rename).
- Config, key and known hosts files are checked for owner and mode.
- Commands are absolute argv lists, no shell, with an empty environment plus
the documented `PULLGATE_*` variables, a timeout that kills the process
group, and an output cap.
- Fail closed: every error, timeout or unclear state means no apply.

**Repo hygiene**
- No real host names, domain names, IP addresses, VPN or tailnet names,
tokens, keys, user IDs, private names of people, or links to private
repositories. Test data is invented.
- New dependencies are justified. GitHub Actions are pinned to a full commit
SHA. Workflows have the smallest `permissions`.
- If the change alters what a message shows, what root or the listener
checks, or where a file goes, `THREAT-MODEL.md` and `DESIGN.md` change in
the same pull request.
- Tests cover the deny paths, not only the happy path. Run
`go test -race ./...` and `go vet ./...` if Go is available.

## Output

List findings, most severe first. For each: severity (critical, high,
medium, low), `file:line`, what is wrong, a concrete way it fails (inputs or
steps → wrong result), and the fix. Mark a finding "unsure" if you could not
confirm it. If you find nothing, say so and list what you checked.

Do not edit files, do not commit, and do not start other agents.
26 changes: 26 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
version: 2
updates:
# Pull request titles look like "chore(deps): bump ...". The chore type
# makes no release.
- package-ecosystem: gomod
directory: /
schedule:
interval: weekly
# Wait 7 days after a new version comes out, so that a bad release can
# be found and pulled first. Security updates do not wait.
cooldown:
default-days: 7
commit-message:
prefix: chore
include: scope

# Pull request titles look like "ci(deps): bump actions/checkout ...".
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
cooldown:
default-days: 7
commit-message:
prefix: ci
include: scope
86 changes: 86 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
name: CI

on:
pull_request:
push:
branches: [main]
schedule:
# Every Monday: find vulnerabilities that became known since the last push.
- cron: "17 5 * * 1"

permissions:
contents: read

concurrency:
# A new push to a pull request cancels the older run for it.
# Each push to main gets its own group, so those runs are never cancelled.
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
cancel-in-progress: true

jobs:
test:
name: test (${{ matrix.go }})
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
# go.mod: the oldest Go we support (the go line in go.mod).
# stable: the newest Go release.
go: [go.mod, stable]
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: ${{ matrix.go == 'go.mod' && 'go.mod' || '' }}
go-version: ${{ matrix.go == 'stable' && 'stable' || '' }}
- name: Check formatting
run: |
unformatted="$(gofmt -l .)"
if [ -n "$unformatted" ]; then
echo "These files are not formatted with gofmt:"
echo "$unformatted"
exit 1
fi
- run: go vet ./...
# The tests need git. GitHub sets CI=true, and then a test fails
# instead of skips when git is missing.
- run: git --version
- run: go test -race ./...
- name: Build static binaries
run: |
for arch in amd64 arm64; do
CGO_ENABLED=0 GOOS=linux GOARCH="$arch" go build -trimpath -o "/tmp/pullgate-$arch" ./cmd/pullgate
done

lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: go.mod
- uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9.3.0
with:
# Dependabot does not update this version. Update it by hand.
version: v2.14.0
# With the tag e2e, the files of the end-to-end test are checked too.
args: --build-tags e2e

vuln:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
# Release binaries are built with the newest Go, so check the
# standard library of that version.
go-version: stable
- name: govulncheck
# Dependabot does not update this version. Update it by hand.
run: go run golang.org/x/vuln/cmd/govulncheck@v1.9.0 ./...
43 changes: 43 additions & 0 deletions .github/workflows/pr-title.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
name: PR title

# The squash merge uses the pull request title as the commit message, and
# release-please reads those messages. So the title must follow
# Conventional Commits. See docs/releasing.md.

on:
# pull_request_target also runs for pull requests from forks. It runs with
# this repository's token, so this workflow must never check out or run
# code from the pull request. It only reads the title.
pull_request_target:
types: [opened, edited, synchronize, reopened]

permissions:
pull-requests: read # read the pull request

concurrency:
# Check only the newest title of a pull request.
group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
cancel-in-progress: true

jobs:
title:
name: Conventional Commits title
runs-on: ubuntu-latest
steps:
- uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
types: |
security
feat
fix
perf
revert
docs
chore
ci
test
refactor
build
style
17 changes: 17 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Release build output
/dist/

# Binary from "go build ./cmd/pullgate"
/pullgate

# Test coverage output
*.out
*.coverprofile
coverage.html

# Editor and OS files
.idea/
.vscode/
*.swp
*~
.DS_Store
61 changes: 61 additions & 0 deletions .golangci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# golangci-lint configuration, v2 format.
# Reference: https://golangci-lint.run/docs/configuration/file/
version: "2"

linters:
# standard: errcheck, govet, ineffassign, staticcheck, unused.
default: standard
enable:
- bodyclose # HTTP response bodies are closed
- errorlint # errors are checked with errors.Is/As and wrapped with %w
- forbidigo # library code does not print (see settings)
- gosec # security problems
- misspell # spelling mistakes in comments and strings
- noctx # network calls take a context.Context
- nolintlint # //nolint comments name the linter and give a reason
- unconvert # type conversions that do nothing

settings:
forbidigo:
# Library code must never print or log on its own: a secret could end
# up in a terminal or a log. Library code gets an io.Writer or a
# *slog.Logger from its caller, and returns values and errors.
# Code in cmd/ talks to the user, so it may print (see exclusions below).
forbid:
- pattern: ^fmt\.Print.*$
msg: library code must not print; return the value or an error
- pattern: ^print(ln)?$
msg: library code must not print; return the value or an error
- pattern: ^os\.(Stdout|Stderr)$
msg: library code must not use stdout or stderr; take an io.Writer
- pattern: ^log\.(Logger\.)?(Print|Fatal|Panic).*$
msg: library code must not log; return an error or take a *slog.Logger
- pattern: ^log\.(Logger\.)?(Output|SetOutput)$
msg: library code must not log; return an error or take a *slog.Logger
- pattern: ^slog\.(Debug|Info|Warn|Error|Log)(Context|Attrs)?$
msg: library code must not use the default logger; take a *slog.Logger
- pattern: ^slog\.(Default|SetDefault)$
msg: library code must not use the default logger; take a *slog.Logger
# Match on types, so an import alias or a *log.Logger cannot hide a call.
analyze-types: true
nolintlint:
require-explanation: true
require-specific: true

exclusions:
rules:
# Code in cmd/ may print. Only the rules about printing and logging
# (their messages start with "library code must not") are off there.
- path: ^cmd/
linters:
- forbidigo
text: library code must not

formatters:
enable:
- gofmt
- goimports
settings:
goimports:
local-prefixes:
- github.com/code6x/pullgate
Loading
Loading