静态代码分析工具

# Clone
git clone https://github.com/NextStat/GoGuard.git
cd GoGuard

# Build Rust core
cargo build --release

# Build Go bridge
cd goguard-go-bridge && go build -o goguard-go-bridge && cd ..

# Install both binaries
cp target/release/goguard /usr/local/bin/
cp goguard-go-bridge/goguard-go-bridge /usr/local/bin/

# macOS (Apple Silicon)
curl -sSL https://github.com/NextStat/GoGuard/releases/latest/download/goguard-darwin-arm64.tar.gz | tar xz
sudo mv goguard goguard-go-bridge /usr/local/bin/

# macOS (Intel)
curl -sSL https://github.com/NextStat/GoGuard/releases/latest/download/goguard-darwin-amd64.tar.gz | tar xz
sudo mv goguard goguard-go-bridge /usr/local/bin/

# Linux (x86_64)
curl -sSL https://github.com/NextStat/GoGuard/releases/latest/download/goguard-linux-amd64.tar.gz | tar xz
sudo mv goguard goguard-go-bridge /usr/local/bin/

goguard update

goguard --version
# goguard 0.1.0 (abc1234)

# Navigate to any Go project
cd ~/my-go-project

# Initialize GoGuard (creates goguard.toml + AGENTS.md + CLAUDE.md + Agent Skills)
goguard init

# Analyze your code
goguard check ./...

# See what changed since last commit
goguard check --diff ./...

# Get a detailed explanation of any rule
goguard explain NIL001

# Auto-fix all critical issues (with test verification)
goguard auto-fix --severity critical --test

# Output SARIF for CI/GitHub Security tab
goguard check --format sarif ./... > results.sarif

  ⚠ NIL001 handler.go:18:22 — nil pointer dereference
    user may be nil (from GetUser return)
    confidence: 0.95

  ✗ ERR001 server.go:42:5 — error return value not checked
    db.Close() returns error, which is ignored

  ⚠ TAINT001 api.go:55:12 — SQL injection
    tainted data flows from r.URL.Query().Get("id") to db.Query()

Found 3 issues (1 critical, 1 error, 1 warning) in 0.14s

goguard check [OPTIONS] [PACKAGES...]

# Analyze entire project
goguard check ./...

# Only critical issues, JSON output
goguard check --severity critical --format json ./...

# CI pipeline — SARIF for GitHub Security tab
goguard check --format sarif ./... > results.sarif

# Diff-aware (only changed packages) — perfect for pre-commit hooks
goguard check --diff ./...

# Analyze a specific package
goguard check ./internal/handler

# Strict nil checking (catches more bugs, may have false positives)
goguard check --strict-params ./...

# Markdown output for AI agents
goguard check --format md ./...

goguard auto-fix [OPTIONS] [PACKAGES...]

# Fix all critical issues, verify with tests
goguard auto-fix --severity critical --test

# Preview what would be fixed (no changes)
goguard auto-fix --dry-run

# Quick mode — fix up to 5 issues, no tests, 60s budget
goguard auto-fix --max-fixes 5 --max-time-secs 60

# Fix a specific package
goguard auto-fix ./internal/handler

# Verbose output to see each iteration
goguard auto-fix -v --test

Iteration 1/10: analyzing...
  Fixed NIL001 handler.go:18 — added nil check
  go build: OK
  go test: OK (47 pass, 0 fail, 3 skip)

Iteration 2/10: analyzing...
  Fixed ERR001 server.go:42 — added error handling
  go build: OK
  go test: OK

Result: 2 fixes applied, 0 skipped
  Before: { critical: 3, error: 5, warning: 8 }
  After:  { critical: 1, error: 4, warning: 8 }
  Build: pass | Tests: 47 pass, 0 fail
  Time: 12.4s

goguard fix <DIAGNOSTIC_ID> [OPTIONS]

# Show the fix (preview)
goguard fix "NIL001-handler.go:18"

# Apply and verify
goguard fix "NIL001-handler.go:18" --apply --verify

# Generate a patch file
goguard fix "NIL001-handler.go:18" --patch > fix.patch
patch -p0 < fix.patch

goguard explain <RULE>

goguard explain NIL001
goguard explain ERR001
goguard explain TAINT001
goguard explain OWN004

NIL001: Nil pointer dereference

A value that may be nil is used in a context that would cause a
runtime panic (field access, method call, index, etc.).

Example:
  user, _ := GetUser(id)
  fmt.Println(user.Name) // user may be nil

Fix: Check for nil before use:
  if user != nil {
      fmt.Println(user.Name)
  }

goguard query [OPTIONS] [EXPRESSION]

# Single query
goguard query 'diagnostics where severity == "critical"'

# Interactive REPL
goguard query --repl

# Inside the REPL:
> diagnostics where severity == "critical"
> diagnostics where rule == "NIL001"
> count
> callers of "(*Server).handleRequest"
> taint paths from "http.Request" to "database/sql"
> help
> quit

goguard init

goguard skills install [--project-dir <DIR>] [--targets <LIST>] [--update true|false]

# Update/reinstall skills in default locations
goguard skills install --update

# Also install into Windsurf + visible repo tree
goguard skills install --targets cursor,windsurf,github --update

goguard setup <TARGET>

# Print config for Claude Code
goguard setup claude-code

# Print config for Cursor
goguard setup cursor

goguard serve [OPTIONS]

# MCP server (usually called by the AI tool, not directly)
goguard serve --mcp

# LSP server
goguard serve --lsp

goguard update

goguard update-agents-md [--path AGENTS.md]

# Generate Python SDK
goguard sdk generate python

# Call an MCP tool via CLI (for SDK integration)
goguard sdk call <TOOL> --params '<JSON>' [--project-dir <DIR>]

# Analyze via SDK call
goguard sdk call goguard_analyze --params '{"packages": ["./..."]}'

# Explain a rule
goguard sdk call goguard_explain --params '{"rule": "NIL001"}'

# Fix a diagnostic
goguard sdk call goguard_fix --params '{"diagnostic_id": "NIL001-handler.go:18"}'

[goguard]
# Minimum severity to report: "info", "warning", "error", "critical"
severity_threshold = "warning"

# Skip files starting with "// Code generated" (default: true)
skip_generated = true

# Maximum diagnostics to report (0 = unlimited)
# max_diagnostics = 0

# Bridge cache directory (auto-detected if omitted)
# cache_dir = "~/.cache/goguard/bridge-cache"

# Maximum cached bridge outputs to retain
# max_cache_entries = 20

# Disable bridge caching entirely
# no_cache = false


# ───────────────────────────────────────────────
# Nil Safety
# ───────────────────────────────────────────────
[rules.nil]
enabled = true

# Strict parameter mode (default: false).
# When false: all pointer parameters are assumed NonNil (fewer reports, may miss bugs).
# When true:  nilable parameters start as MaybeNil. GoGuard then applies entrypoint
#             models for known frameworks (net/http, gin, echo, fiber, grpc, testing)
#             to seed handler params back to NonNil — so framework handlers stay clean,
#             but internal functions that receive nil pointers are caught.
# strict_params = false

# User-provided nil models.
# Tell GoGuard whether specific functions return nil or not.
# Values: "nonnull" (never returns nil), "nilable" (can return nil)
# For multi-return functions, append #<index>: "os.Open#0" = the *File return.
[rules.nil.models]
# "mycompany/internal/db.GetDB" = "nonnull"
# "mycompany/internal/cache.Get#0" = "nilable"
# "context.WithCancel#0" = "nonnull"


# ───────────────────────────────────────────────
# Error Checking
# ───────────────────────────────────────────────
[rules.errcheck]
enabled = true
# Glob patterns for functions whose error returns can be safely ignored
ignore = ["fmt.Print*", "fmt.Fprint*"]


# ───────────────────────────────────────────────
# Concurrency Analysis
# ───────────────────────────────────────────────
[rules.concurrency]
enabled = true


# ───────────────────────────────────────────────
# Resource Lifecycle / Ownership
# ───────────────────────────────────────────────
[rules.ownership]
enabled = true


# ───────────────────────────────────────────────
# Exhaustiveness Checking
# ───────────────────────────────────────────────
[rules.exhaustive]
enabled = true


# ───────────────────────────────────────────────
# Taint Analysis (Security)
# ───────────────────────────────────────────────
[rules.taint]
enabled = true

[rules.nil.models]
# Single-return: function never returns nil
"mycompany/pkg.NewClient" = "nonnull"

# Multi-return: the *File at index 0 is never nil when err==nil
# (GoGuard already handles the Go error convention for stdlib,
#  but for your own code you may need to specify)
"mycompany/pkg.Open#0" = "nonnull"

# Explicitly mark a function as possibly returning nil
"mycompany/pkg.FindUser#0" = "nilable"

//goguard:nonnull
user := GetUser(id) // GoGuard will treat this as non-nil

result := riskyCall() //goguard:nonnull

// ✗ BAD: user may be nil
user, _ := GetUser(id)
fmt.Println(user.Name) // ← NIL001: nil pointer dereference

// ✓ GOOD: nil check before use
user, err := GetUser(id)
if err != nil {
    return err
}
fmt.Println(user.Name) // safe

// ✗ BAD: panics if x is not a string
s := x.(string) // ← NIL002

// ✓ GOOD: comma-ok pattern
s, ok := x.(string)
if !ok {
    return errors.New("not a string")
}

// ✗ BAD: writing to nil map panics
var m map[string]int
m["key"] = 42 // ← NIL004: panic

// ✓ GOOD: initialize the map
m := make(map[string]int)
m["key"] = 42

// ✗ BAD: error completely ignored
os.Open("/tmp/file") // ← ERR001

// ✗ BAD: error explicitly discarded
f, _ := os.Open("/tmp/file") // ← ERR002

// ✓ GOOD: error properly checked
f, err := os.Open("/tmp/file")
if err != nil {
    return fmt.Errorf("opening file: %w", err)
}
defer f.Close()

[rules.errcheck]
ignore = ["fmt.Print*", "fmt.Fprint*", "(*log.Logger).Print*"]

// ✗ BAD: data race on count
count := 0
go func() { count++ }() // ← RACE001

// ✓ GOOD: use atomic
var count int64
go func() { atomic.AddInt64(&count, 1) }()

// ✗ BAD: all goroutines see the last item
for _, v := range items {
    go func() { process(v) }() // ← RACE002
}

// ✓ GOOD: pass as argument
for _, v := range items {
    go func(v Item) { process(v) }(v)
}

// ✗ BAD: goroutine runs forever
go func() { // ← LEAK001
    for {
        doWork()
    }
}()

// ✓ GOOD: use context for cancellation
go func(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            return
        default:
            doWork()
        }
    }
}(ctx)

// ✗ BAD: f is never closed (OWN001)
f, err := os.Open(path)
if err != nil { return err }
data, _ := io.ReadAll(f)

// ✗ BAD: not using defer (OWN004)
f, err := os.Open(path)
if err != nil { return err }
data, _ := io.ReadAll(f)
f.Close() // if ReadAll panics, f leaks

// ✓ GOOD
f, err := os.Open(path)
if err != nil { return err }
defer f.Close()
data, _ := io.ReadAll(f)

type Shape interface { Area() float64 }
type Circle struct { ... }
type Square struct { ... }
type Triangle struct { ... } // new type added

// ✗ BAD: Triangle not handled (EXH001)
switch s := shape.(type) {
case *Circle:  ...
case *Square:  ...
}

// ✓ GOOD: exhaustive or explicit default
switch s := shape.(type) {
case *Circle:   ...
case *Square:   ...
case *Triangle: ...
}

// ✗ BAD: SQL injection (TAINT001)
id := r.URL.Query().Get("id")
db.Query("SELECT * FROM users WHERE id=" + id)

// ✓ GOOD: parameterized query
id := r.URL.Query().Get("id")
db.Query("SELECT * FROM users WHERE id=$1", id)

// ✗ BAD: command injection (TAINT002)
cmd := exec.Command("sh", "-c", userInput)

// ✓ GOOD: pass as separate arguments
cmd := exec.Command("grep", "-r", userInput, "/safe/dir")

// ✗ BAD: path traversal (TAINT003)
path := filepath.Join("/uploads", userInput)
os.ReadFile(path) // userInput = "../../etc/passwd"

// ✓ GOOD: validate the resolved path
path := filepath.Join("/uploads", filepath.Clean(userInput))
if !strings.HasPrefix(path, "/uploads/") {
    return errors.New("invalid path")
}

# Print the config snippet
goguard setup claude-code

{
  "mcpServers": {
    "goguard": {
      "command": "/usr/local/bin/goguard",
      "args": ["serve", "--mcp"]
    }
  }
}

goguard setup cursor

{
  "mcpServers": {
    "goguard": {
      "command": "/usr/local/bin/goguard",
      "args": ["serve", "--mcp"]
    }
  }
}

goguard setup windsurf

{
  "mcpServers": {
    "goguard": {
      "command": "/usr/local/bin/goguard",
      "args": ["serve", "--mcp"]
    }
  }
}

goguard setup codex

[mcp_servers.goguard]
command = "/usr/local/bin/goguard"
args = ["serve", "--mcp"]

goguard setup zed

{
  "context_servers": {
    "goguard": {
      "command": "/usr/local/bin/goguard",
      "args": ["serve", "--mcp"]
    }
  }
}

goguard setup opencode

{
  "mcp": {
    "goguard": {
      "type": "local",
      "command": ["/usr/local/bin/goguard", "serve", "--mcp"],
      "enabled": true
    }
  }
}

goguard setup vscode

{
  "goguard.path": "/usr/local/bin/goguard",
  "goguard.lsp.enabled": true,
  "goguard.lsp.args": ["serve", "--lsp"]
}

{
  "id": "NIL001-handler.go:18",
  "rule": "NIL001",
  "severity": "critical",
  "title": "nil pointer dereference",
  "location": {"file": "handler.go", "line": 18, "column": 22},
  "fix_available": true
}

pip install goguard

from goguard import GoGuard

g = GoGuard("/path/to/go/project")

# Analyze
result = g.analyze(severity="error")
for d in result.diagnostics:
    print(f"{d.rule} {d.location.file}:{d.location.line} — {d.title}")

# Get full details
detail = g.explain(result.diagnostics[0].id)

# Fix a diagnostic
fix = g.fix(result.diagnostics[0].id)
fix.apply()  # writes to disk

# Auto-fix all errors
report = g.auto_fix(severity="error", dry_run=True)
print(f"Would fix {report.fixes_applied} issues")

# Run JavaScript against analysis data (Code Mode)
result = g.execute("goguard.diagnostics().length")
print(result.output)

# Query with GoGuard QL
result = g.query('diagnostics where severity == "critical"')

┌──────────────────────────────────────────────────┐
│  goguard-go-bridge  (Go, "Fat Bridge")           │
│                                                  │
│  go/packages.Load() → go/types → go/ssa          │
│      ↓                                           │
│  SSA + CFG + Call Graph + Interface Table         │
│      ↓                                           │
│  Serialize → FlatBuffers IR                       │
└───────────────────┬──────────────────────────────┘
                    │ stdio
                    ▼
┌──────────────────────────────────────────────────┐
│  goguard  (Rust, analysis core)                  │
│                                                  │
│  Decode IR → Salsa DB                             │
│      ↓                                           │
│  Analysis passes:                                │
│    • Nil lattice (forward dataflow, fixpoint)    │
│    • Errcheck (error variable tracking)          │
│    • Concurrency (goroutine + shared state)      │
│    • Ownership (resource state machine)          │
│    • Exhaustiveness (enum/interface coverage)    │
│    • Taint (source → sink propagation)           │
│      ↓                                           │
│  Diagnostics → Formatters (human/JSON/SARIF/MD)  │
│      ↓                                           │
│  Output: CLI / MCP server / LSP server / Pipe    │
└──────────────────────────────────────────────────┘

# Run Rust tests
cargo test --workspace

# Run Go bridge tests
cd goguard-go-bridge && go test ./...

# Check formatting and lints
cargo fmt --check
cargo clippy -- -D warnings