fix(runner): 完善工具执行安全校验与能力令牌闭环

- Gateway 签发 CapabilityToken 并随工具请求下发给 Runner
- Runner 验证 Token 签名/TTL/工具白名单 + 路径 allowlist 校验
- Token 从 URL query 迁移至 Authorization Header
- 添加 WebSocket 并发写保护、工具注册、Shell 自动检测
- 路径判定排除 URL 等非路径字符串，相对路径基于 workdir 解析

Author: Cai-Tang-www

internal/gateway/protocol/runner.go

@@ -1,6 +1,10 @@
 package protocol
 
-import "encoding/json"
+import (
+	"encoding/json"
+
+	"neo-code/internal/security"
+)
 
 const (
 	// MethodGatewayRegisterRunner 表示 runner 向网关注册。
@@ -32,10 +36,11 @@ type ExecuteToolResultParams struct {
 
 // ToolRequestParams 是网关推送给 runner 的工具执行请求。
 type ToolRequestParams struct {
-	RequestID  string          `json:"request_id"`
-	SessionID  string          `json:"session_id"`
-	RunID      string          `json:"run_id"`
-	ToolCallID string          `json:"tool_call_id"`
-	ToolName   string          `json:"tool_name"`
-	Arguments  json.RawMessage `json:"arguments"`
+	RequestID       string                   `json:"request_id"`
+	SessionID       string                   `json:"session_id"`
+	RunID           string                   `json:"run_id"`
+	ToolCallID      string                   `json:"tool_call_id"`
+	ToolName        string                   `json:"tool_name"`
+	Arguments       json.RawMessage          `json:"arguments"`
+	CapabilityToken *security.CapabilityToken `json:"capability_token,omitempty"`
 }

internal/gateway/runner_tool.go

@@ -87,18 +87,37 @@ func (m *RunnerToolManager) DispatchToolRequest(ctx context.Context, sessionID s
 	m.pending[requestID] = pending
 	m.mu.Unlock()
 
+	// 签发 capability token（如果 signer 已配置）
+	var capToken *security.CapabilityToken
+	if m.capabilitySigner != nil {
+		workdir := ""
+		if record, ok := m.registry.Record(connectionID); ok {
+			workdir = record.Workdir
+		}
+		signed, err := m.NewCapabilityToken(sessionID, runID, toolName, workdir)
+		if err != nil {
+			m.logger.Printf("failed to sign capability token: %v", err)
+		} else if signed != nil {
+			capToken = signed
+		}
+	}
+
 	// 构建通知并推送到 runner 连接
+	params := map[string]any{
+		"request_id":   requestID,
+		"session_id":   sessionID,
+		"run_id":       runID,
+		"tool_call_id": toolCallID,
+		"tool_name":    toolName,
+		"arguments":    arguments,
+	}
+	if capToken != nil {
+		params["capability_token"] = capToken
+	}
 	notification := map[string]any{
 		"jsonrpc": "2.0",
 		"method":  protocol.MethodGatewayToolRequest,
-		"params": map[string]any{
-			"request_id":   requestID,
-			"session_id":   sessionID,
-			"run_id":       runID,
-			"tool_call_id": toolCallID,
-			"tool_name":    toolName,
-			"arguments":    arguments,
-		},
+		"params":  params,
 	}
 	if !m.relay.SendJSONRPCPayload(connectionID, notification) {
 		m.mu.Lock()

internal/runner/capability.go

@@ -1,13 +1,18 @@
 package runner
 
 import (
+	"encoding/json"
 	"path/filepath"
 	goruntime "runtime"
 	"strings"
+	"time"
+
+	"neo-code/internal/security"
 )
 
 // CapSigner 在 runner 端负责验证 capability token 和 workspace 边界。
 type CapSigner struct {
+	capVerifier      *security.CapabilitySigner
 	workdirAllowlist []string
 }
 
@@ -18,14 +23,99 @@ func NewCapSigner(workdirAllowlist []string) *CapSigner {
 	}
 }
 
+// SetCapVerifier 设置用于验证 capability token 签名的验签器。
+func (s *CapSigner) SetCapVerifier(verifier *security.CapabilitySigner) {
+	s.capVerifier = verifier
+}
+
 // VerifyToolRequest 验证工具执行请求是否被允许。
 // 检查：
-// 1. 工具名是否被允许（默认所有工具允许，除非有 capability token）
+// 1. CapabilityToken 签名、TTL、工具白名单（如果提供了 token）
 // 2. 路径是否在工作区 allowlist 内
 func (s *CapSigner) VerifyToolRequest(req ToolExecutionRequest, workdir string) error {
-	_ = req // reserved for future capability token validation
-	_ = workdir
-	return nil // no additional checks for MVP; capability token validation added later
+	// 如果提供了 capability token，验证其签名和权限
+	if req.CapabilityToken != nil {
+		if s.capVerifier != nil {
+			if err := s.capVerifier.Verify(*req.CapabilityToken); err != nil {
+				return ErrCapabilitySignatureInvalid
+			}
+		}
+		if err := req.CapabilityToken.ValidateAt(time.Now()); err != nil {
+			return ErrCapabilityTokenExpired
+		}
+		if !isToolAllowed(req.CapabilityToken.AllowedTools, req.ToolName) {
+			return ErrCapabilityToolNotAllowed
+		}
+	}
+
+	// 验证路径是否在 allowlist 内
+	if req.Arguments != nil {
+		if err := s.verifyPathsInArgs(req.Arguments, workdir); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// verifyPathsInArgs 检查参数中的路径是否在 allowlist 范围内。
+func (s *CapSigner) verifyPathsInArgs(args json.RawMessage, workdir string) error {
+	if len(s.workdirAllowlist) == 0 {
+		return nil
+	}
+	var m map[string]any
+	if err := json.Unmarshal(args, &m); err != nil {
+		return nil
+	}
+	for _, v := range m {
+		str, ok := v.(string)
+		if !ok {
+			continue
+		}
+		if looksLikePath(str) {
+			resolved := resolvePath(str, workdir)
+			if err := s.VerifyPath(resolved); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+// looksLikePath 判断字符串是否看起来像文件路径。
+func looksLikePath(s string) bool {
+	if strings.Contains(s, "://") {
+		return false
+	}
+	return strings.Contains(s, "/") || strings.Contains(s, "\\") ||
+		strings.HasPrefix(s, ".") || filepath.IsAbs(s)
+}
+
+// resolvePath 将 target 基于 workdir 解析为绝对路径，用于 allowlist 比较。
+func resolvePath(target string, workdir string) string {
+	trimmed := strings.TrimSpace(target)
+	if trimmed == "" {
+		return ""
+	}
+	if filepath.IsAbs(trimmed) {
+		return trimmed
+	}
+	base := strings.TrimSpace(workdir)
+	if base != "" {
+		return filepath.Join(base, trimmed)
+	}
+	return trimmed
+}
+
+// isToolAllowed 判断工具名是否在 token 允许列表中。
+func isToolAllowed(allowedTools []string, toolName string) bool {
+	normalized := strings.ToLower(strings.TrimSpace(toolName))
+	for _, allowed := range allowedTools {
+		if strings.ToLower(strings.TrimSpace(allowed)) == normalized {
+			return true
+		}
+	}
+	return false
 }
 
 // VerifyPath 验证目标路径是否在 allowlist 范围内。

internal/runner/runner.go

@@ -9,13 +9,19 @@ import (
 	"math/rand"
 	"net/http"
 	"os"
+	goruntime "runtime"
 	"strings"
 	"sync"
 	"time"
 
 	"github.com/gorilla/websocket"
 
 	"neo-code/internal/tools"
+	"neo-code/internal/tools/bash"
+	diagnosetool "neo-code/internal/tools/diagnose"
+	"neo-code/internal/tools/filesystem"
+	"neo-code/internal/tools/todo"
+	"neo-code/internal/tools/webfetch"
 )
 
 // Runner 是本地执行守护进程，主动连接云端 Gateway，接收工具执行请求。
@@ -26,6 +32,7 @@ type Runner struct {
 	capSigner  *CapSigner
 
 	mu      sync.Mutex
+	writeMu sync.Mutex // 保护 WebSocket 并发写
 	running bool
 	cancel  context.CancelFunc
 }
@@ -38,6 +45,7 @@ type Config struct {
 	Token             string
 	Workdir           string
 	WorkdirAllowlist  []string
+	Shell             string // 用于 bash 工具，空值自动检测
 	HeartbeatInterval time.Duration
 	ReconnectBackoffMin time.Duration
 	ReconnectBackoffMax time.Duration
@@ -71,7 +79,38 @@ func New(cfg Config) (*Runner, error) {
 		logger = log.New(os.Stderr, "runner: ", log.LstdFlags)
 	}
 
+	shell := cfg.Shell
+	if shell == "" {
+		if goruntime.GOOS == "windows" {
+			shell = "cmd"
+		} else {
+			shell = "bash"
+		}
+	}
+	workdir := cfg.Workdir
+	if workdir == "" {
+		var err error
+		workdir, err = os.Getwd()
+		if err != nil {
+			return nil, fmt.Errorf("runner: get workdir: %w", err)
+		}
+	}
+
 	toolMgr := tools.NewRegistry()
+	toolMgr.Register(filesystem.New(workdir))
+	toolMgr.Register(filesystem.NewWrite(workdir))
+	toolMgr.Register(filesystem.NewGrep(workdir))
+	toolMgr.Register(filesystem.NewGlob(workdir))
+	toolMgr.Register(filesystem.NewEdit(workdir))
+	toolMgr.Register(filesystem.NewMove(workdir))
+	toolMgr.Register(filesystem.NewCopy(workdir))
+	toolMgr.Register(filesystem.NewDelete(workdir))
+	toolMgr.Register(filesystem.NewCreateDir(workdir))
+	toolMgr.Register(filesystem.NewRemoveDir(workdir))
+	toolMgr.Register(bash.New(workdir, shell, cfg.RequestTimeout))
+	toolMgr.Register(webfetch.New(webfetch.Config{Timeout: cfg.RequestTimeout}))
+	toolMgr.Register(diagnosetool.New())
+	toolMgr.Register(todo.New())
 
 	capSigner := NewCapSigner(cfg.WorkdirAllowlist)
 
@@ -130,12 +169,12 @@ func (r *Runner) Run(ctx context.Context) error {
 
 func (r *Runner) connectAndServe(ctx context.Context) error {
 	url := fmt.Sprintf("ws://%s/ws", r.cfg.GatewayAddress)
-	if r.cfg.Token != "" {
-		url += "?token=" + r.cfg.Token
-	}
 
 	header := http.Header{}
 	header.Set("X-Runner-ID", r.cfg.RunnerID)
+	if r.cfg.Token != "" {
+		header.Set("Authorization", "Bearer "+r.cfg.Token)
+	}
 
 	dialer := websocket.Dialer{
 		HandshakeTimeout: r.cfg.RequestTimeout,
@@ -149,7 +188,7 @@ func (r *Runner) connectAndServe(ctx context.Context) error {
 	}
 	defer conn.Close()
 
-	r.logger.Printf("connected to gateway at %s", url)
+	r.logger.Printf("connected to gateway at %s (runner=%s)", r.cfg.GatewayAddress, r.cfg.RunnerID)
 
 	// 认证
 	if err := r.sendRequest(conn, "gateway.authenticate", map[string]string{
@@ -224,6 +263,24 @@ func (r *Runner) handleToolRequest(ctx context.Context, conn *websocket.Conn, ms
 
 	r.logger.Printf("executing tool: %s (request_id=%s)", req.ToolName, req.RequestID)
 
+	// 验证 capability token 和路径边界
+	if err := r.capSigner.VerifyToolRequest(req, r.cfg.Workdir); err != nil {
+		r.logger.Printf("tool request denied: %v", err)
+		resultParams := map[string]any{
+			"request_id":   req.RequestID,
+			"session_id":   req.SessionID,
+			"run_id":       req.RunID,
+			"runner_id":    r.cfg.RunnerID,
+			"tool_call_id": req.ToolCallID,
+			"content":      fmt.Sprintf("tool request denied: %v", err),
+			"is_error":     true,
+		}
+		if sendErr := r.sendRequest(conn, "gateway.executeToolResult", resultParams); sendErr != nil {
+			r.logger.Printf("failed to send denied result: %v", sendErr)
+		}
+		return
+	}
+
 	// 执行工具
 	execCtx, cancel := context.WithTimeout(ctx, r.cfg.RequestTimeout)
 	defer cancel()
@@ -268,6 +325,8 @@ func (r *Runner) handlePing(conn *websocket.Conn, msg map[string]any) {
 		"result":  "pong",
 	}
 	data, _ := json.Marshal(response)
+	r.writeMu.Lock()
+	defer r.writeMu.Unlock()
 	if err := conn.WriteMessage(websocket.TextMessage, data); err != nil {
 		r.logger.Printf("failed to send pong: %v", err)
 	}
@@ -304,6 +363,8 @@ func (r *Runner) sendRequest(conn *websocket.Conn, method string, params any) er
 		return fmt.Errorf("marshal request: %w", err)
 	}
 
+	r.writeMu.Lock()
+	defer r.writeMu.Unlock()
 	if err := conn.SetWriteDeadline(time.Now().Add(r.cfg.RequestTimeout)); err != nil {
 		return fmt.Errorf("set write deadline: %w", err)
 	}

internal/runner/types.go

@@ -4,6 +4,8 @@ import (
 	"encoding/json"
 	"errors"
 	"time"
+
+	"neo-code/internal/security"
 )
 
 var (
@@ -23,12 +25,13 @@ var (
 
 // ToolExecutionRequest 表示从网关收到的工具执行请求。
 type ToolExecutionRequest struct {
-	RequestID  string          `json:"request_id"`
-	SessionID  string          `json:"session_id"`
-	RunID      string          `json:"run_id"`
-	ToolCallID string          `json:"tool_call_id"`
-	ToolName   string          `json:"tool_name"`
-	Arguments  json.RawMessage `json:"arguments"`
+	RequestID       string                   `json:"request_id"`
+	SessionID       string                   `json:"session_id"`
+	RunID           string                   `json:"run_id"`
+	ToolCallID      string                   `json:"tool_call_id"`
+	ToolName        string                   `json:"tool_name"`
+	Arguments       json.RawMessage          `json:"arguments"`
+	CapabilityToken *security.CapabilityToken `json:"capability_token,omitempty"`
 }
 
 // ToolExecutionResult 表示工具执行结果。

www/guide/feishu-remote-setup.md

@@ -334,10 +334,17 @@ Runner 断连后会自动重连，采用指数退避 + 随机抖动策略：
 
 ### 8.4 安全边界
 
-- Runner 只执行 Gateway 签发并签名的工具请求（CapabilityToken HMAC-SHA256 校验）
-- Token 有过期时间（TTL），过期请求会被拒绝
+当前已实现：
+
+- Runner 验证 Gateway 签发的 CapabilityToken（HMAC-SHA256 签名校验、TTL 过期检查、工具白名单）
+- Token 有过期时间（5 分钟 TTL），过期请求会被拒绝
 - 支持配置工作区路径白名单（`WorkdirAllowlist`），拒绝越界路径访问
-- 所有工具在 Runner 本机执行，结果通过 Gateway 加密回传
+- 所有工具在 Runner 本机执行
+
+传输安全注意事项：
+
+- Runner 与 Gateway 之间当前使用明文 WebSocket（`ws://`），建议仅在受信任的本地网络中使用，或通过 SSH 隧道 / VPN 加固传输层
+- TLS 加密传输（`wss://`）计划在后续版本支持
 
 ### 8.5 错误提示