Feature(Go): per-device locks, a global call gate and tool-call audit

Add the three cross-cutting guards the Go MCP endpoint needs before any
tool talks to a client. Each tools/call now takes one of MaxConcurrency
global slots and, for single-host tools, that host's device lock; both are
non-blocking, so contention returns -32003 instead of queueing. Panicking
handlers are converted to -32000 rather than dropping the connection.

Write one mcp.tool.call audit record per named call, including rejected
ones: actor/role/source, tool, device, ok/code, duration, a size-only
result summary and a truncated argument digest. Commands keep only their
first word plus length, and free-form or credential fields (text, message,
body, headers, password, token) are replaced by their size, so secrets do
not reach the audit file.

Co-Authored-By: deepseek-flash
This commit is contained in:
yuanyuanxianganddeepseek-flash committed 2026-11-12 21:05:37 +01:00
1 parent 774c0d2545
commit 1076e7614a
4 files changed
+571 -4

No files matched your search

+123
View File
@@ -0,0 +1,123 @@
package mcp
import (
"encoding/json"
"fmt"
"strings"
"time"
"unicode/utf8"
)
// auditArgsMaxBytes bounds the argument digest written to the audit file. The
// full payload never goes there: commands can contain passwords and request
// bodies can be large.
const auditArgsMaxBytes = 512
// auditCall writes one mcp.tool.call record per tools/call, matching the Win32
// server's fields (design §4.4). actor/role/source distinguish it from browser
// sessions, which audit as the logged-in username.
func (s *Server) auditCall(tool, deviceID string, args json.RawMessage, result any, rerr *rpcError, elapsed time.Duration) {
fields := map[string]any{
"actor": "mcp",
"role": "admin",
"source": "mcp",
"tool": tool,
"device": "-",
"ok": rerr == nil,
"code": 0,
"ms": elapsed.Milliseconds(),
"args": summarizeArgs(args),
}
if deviceID != "" {
fields["device"] = deviceID
}
if rerr != nil {
fields["code"] = rerr.Code
fields["result"] = rerr.Message
} else {
fields["result"] = resultSize(result)
}
s.log.Audit("mcp.tool.call", fields)
}
// redactedArgKeys name top-level arguments whose value is user content or a
// credential. They are replaced by their size so the audit trail records that
// something was sent, without copying it: terminal commands, chat text, HTTP
// bodies and headers routinely carry passwords.
var redactedArgKeys = map[string]bool{
"text": true,
"message": true,
"body": true,
"headers": true,
"password": true,
"token": true,
}
// summarizeArgs renders a compact, truncated argument digest. A "command"
// value is reduced to its first word and length so terminal passwords never
// reach the audit file; other sensitive values are replaced by their size. The
// full payload stays out of the audit file entirely.
func summarizeArgs(raw json.RawMessage) string {
if len(raw) == 0 || string(raw) == "null" {
return "{}"
}
var obj map[string]any
if err := json.Unmarshal(raw, &obj); err != nil {
return fmt.Sprintf("<unparsed %d bytes>", len(raw))
}
for key, value := range obj {
if key == "command" {
if command, ok := value.(string); ok {
obj[key] = commandDigest(command)
}
continue
}
if redactedArgKeys[key] {
obj[key] = redactedDigest(value)
}
}
b, err := json.Marshal(obj)
if err != nil {
return "{}"
}
return truncateUTF8(string(b), auditArgsMaxBytes)
}
// redactedDigest replaces a sensitive value with its serialized size. The
// marker avoids angle brackets so encoding/json does not escape it.
func redactedDigest(value any) string {
b, err := json.Marshal(value)
if err != nil {
return "redacted"
}
return fmt.Sprintf("redacted(%d bytes)", len(b))
}
func commandDigest(command string) string {
first := command
if i := strings.IndexAny(command, " \t"); i >= 0 {
first = command[:i]
}
return fmt.Sprintf("%s (len=%d)", first, len(command))
}
func resultSize(result any) string {
b, err := json.Marshal(result)
if err != nil {
return "?"
}
return fmt.Sprintf("%d bytes", len(b))
}
// truncateUTF8 cuts s to at most max bytes, including the ellipsis, without
// splitting a rune.
func truncateUTF8(s string, max int) string {
if len(s) <= max {
return s
}
cut := max - len("…")
for cut > 0 && !utf8.RuneStart(s[cut]) {
cut--
}
return s[:cut] + "…"
}
+87
View File
@@ -0,0 +1,87 @@
package mcp
import (
"encoding/json"
"fmt"
"sync"
"time"
)
// localReadTools answer from the server's own state (device hub, history,
// audit file) and never open a channel to a client. Everything else is assumed
// to act on one host, so a call that names an id takes that host's lock.
var localReadTools = map[string]bool{
"list_hosts": true,
"get_host_detail": true,
"get_server_status": true,
"get_audit_log": true,
}
// deviceLocks enforces one in-flight device operation per host. The lock is
// per device, not per channel: the client can share state between the main
// connection and its sub-connections, so overlapping commands only make the
// situation harder to reason about (design §9).
type deviceLocks struct {
mu sync.Mutex
held map[string]deviceHold
}
// deviceHold describes the call currently owning a device, so a rejection can
// tell the caller who is in the way and for how long.
type deviceHold struct {
tool string
since time.Time
}
func newDeviceLocks() *deviceLocks {
return &deviceLocks{held: make(map[string]deviceHold)}
}
// tryAcquire takes the device lock without waiting. The second return value is
// false when another call holds it; held then describes that call.
func (l *deviceLocks) tryAcquire(deviceID, tool string) (held deviceHold, ok bool) {
l.mu.Lock()
defer l.mu.Unlock()
if h, busy := l.held[deviceID]; busy {
return h, false
}
l.held[deviceID] = deviceHold{tool: tool, since: time.Now()}
return deviceHold{}, true
}
func (l *deviceLocks) release(deviceID string) {
l.mu.Lock()
delete(l.held, deviceID)
l.mu.Unlock()
}
// deviceIDFromArgs extracts the one host a tool call targets. Tools with a
// batch `ids` array are handled by their handler one id at a time (matching the
// Win32 server); this function deliberately looks only at the single-host
// spellings.
func deviceIDFromArgs(raw json.RawMessage) string {
if len(raw) == 0 || string(raw) == "null" {
return ""
}
var args struct {
ID string `json:"id"`
DeviceID string `json:"device_id"`
}
if err := json.Unmarshal(raw, &args); err != nil {
// Malformed arguments are reported by the handler as -32602; there is
// no device to lock here.
return ""
}
if args.ID != "" {
return args.ID
}
return args.DeviceID
}
// busyMessage mirrors the Win32 server's -32003 text:
// "Device busy: another request is pending for this host (tool=..., elapsed=Ns)".
func busyMessage(held deviceHold) string {
return fmt.Sprintf(
"Device busy: another request is pending for this host (tool=%s, elapsed=%ds)",
held.tool, int(time.Since(held.since).Seconds()))
}
+310
View File
@@ -0,0 +1,310 @@
package mcp
import (
"context"
"encoding/json"
"os"
"path/filepath"
"strings"
"sync"
"testing"
"github.com/yuanyuanxiang/SimpleRemoter/server/go/logger"
)
// blockingListFiles installs a list_files handler that blocks while id ==
// blockID, so a second call for that host can be checked against the lock.
func blockingListFiles(t *testing.T, s *Server, blockID string) (entered chan struct{}, release func()) {
t.Helper()
entered = make(chan struct{})
done := make(chan struct{})
var once sync.Once
s.handlers["list_files"] = func(_ context.Context, args json.RawMessage) (any, *rpcError) {
var a struct {
ID string `json:"id"`
}
_ = json.Unmarshal(args, &a)
if a.ID == blockID {
once.Do(func() { close(entered) })
<-done
}
return newToolResult("ok", map[string]any{"id": a.ID}), nil
}
return entered, func() { close(done) }
}
func listFilesCall(t *testing.T, s *Server, id string) (any, *rpcError) {
t.Helper()
return s.callTool(context.Background(), json.RawMessage(
`{"name":"list_files","arguments":{"id":"`+id+`","path":"/"}}`))
}
func TestDeviceLockRejectsSecondCall(t *testing.T) {
s := testServer(t, false)
entered, release := blockingListFiles(t, s, "1001")
type outcome struct {
res any
err *rpcError
}
first := make(chan outcome, 1)
go func() {
res, rerr := listFilesCall(t, s, "1001")
first <- outcome{res, rerr}
}()
<-entered
_, rerr := listFilesCall(t, s, "1001")
if rerr == nil || rerr.Code != CodeBusy {
t.Fatalf("second same-host call error = %+v, want -32003", rerr)
}
if !strings.Contains(rerr.Message, "tool=list_files") || !strings.Contains(rerr.Message, "elapsed=") {
t.Fatalf("busy message = %q, want tool and elapsed", rerr.Message)
}
// A different host is a different lock and must not be blocked.
if _, rerr = listFilesCall(t, s, "2002"); rerr != nil {
t.Fatalf("other-host call error = %+v, want success", rerr)
}
release()
if got := <-first; got.err != nil {
t.Fatalf("first call error = %+v, want success", got.err)
}
// The lock is released once the call returns.
if _, rerr = listFilesCall(t, s, "1001"); rerr != nil {
t.Fatalf("call after release error = %+v, want success", rerr)
}
}
func TestDeviceLockReleasedOnContextCancel(t *testing.T) {
s := testServer(t, false)
entered := make(chan struct{})
var once sync.Once
s.handlers["list_files"] = func(ctx context.Context, _ json.RawMessage) (any, *rpcError) {
once.Do(func() { close(entered) })
<-ctx.Done()
return nil, errf(CodeTimeout, "request cancelled")
}
ctx, cancel := context.WithCancel(context.Background())
done := make(chan struct{})
go func() {
defer close(done)
_, _ = s.callTool(ctx, json.RawMessage(
`{"name":"list_files","arguments":{"id":"1001"}}`))
}()
<-entered
cancel()
<-done
// Replace the cancelling handler before reusing the host: the lock must
// already be free, and this handler returns immediately.
s.handlers["list_files"] = func(_ context.Context, _ json.RawMessage) (any, *rpcError) {
return newToolResult("ok", map[string]any{"id": "1001"}), nil
}
if _, rerr := listFilesCall(t, s, "1001"); rerr != nil {
t.Fatalf("call after cancel error = %+v, want success (lock must be free)", rerr)
}
}
func TestGlobalConcurrencyGate(t *testing.T) {
log := logger.New(logger.Config{Level: logger.LevelError,
File: filepath.Join(t.TempDir(), "mcp-test.log")})
t.Cleanup(func() { _ = log.Close() })
s := New(Config{Token: testToken, MaxConcurrency: 1, Log: log})
entered, release := blockingListFiles(t, s, "1001")
type outcome struct {
res any
err *rpcError
}
first := make(chan outcome, 1)
go func() {
res, rerr := listFilesCall(t, s, "1001")
first <- outcome{res, rerr}
}()
<-entered
// A different host still needs a global slot, and there is only one.
_, rerr := listFilesCall(t, s, "2002")
if rerr == nil || rerr.Code != CodeBusy {
t.Fatalf("second call error = %+v, want -32003", rerr)
}
if !strings.Contains(rerr.Message, "concurrent") {
t.Fatalf("concurrency message = %q", rerr.Message)
}
release()
if got := <-first; got.err != nil {
t.Fatalf("first call error = %+v", got.err)
}
if _, rerr = listFilesCall(t, s, "2002"); rerr != nil {
t.Fatalf("call after slot freed error = %+v, want success", rerr)
}
}
// readAuditRecords returns the audit JSON lines written so far.
func readAuditRecords(t *testing.T, path string) []map[string]any {
t.Helper()
data, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read audit file: %v", err)
}
var out []map[string]any
for line := range strings.SplitSeq(strings.TrimSpace(string(data)), "\n") {
if line == "" {
continue
}
var rec map[string]any
if err := json.Unmarshal([]byte(line), &rec); err != nil {
t.Fatalf("parse audit line %q: %v", line, err)
}
out = append(out, rec)
}
return out
}
func TestToolCallAudit(t *testing.T) {
dir := t.TempDir()
auditPath := filepath.Join(dir, "audit.log")
log := logger.New(logger.Config{
Level: logger.LevelError,
File: filepath.Join(dir, "server.log"),
AuditFile: auditPath,
})
t.Cleanup(func() { _ = log.Close() })
s := New(Config{Token: testToken, Log: log})
s.handlers["terminal_exec"] = func(_ context.Context, _ json.RawMessage) (any, *rpcError) {
return newToolResult("done", map[string]any{"output": "secret-output"}), nil
}
text, _, rerr := callLocal(t, s, "terminal_exec",
`{"id":"1001","command":"mysql -pTopSecret --batch"}`)
if rerr != nil {
t.Fatalf("terminal_exec error = %+v (text %q)", rerr, text)
}
if _, _, rerr = callLocal(t, s, "nope", `{}`); rerr == nil || rerr.Code != CodeMethodNotFound {
t.Fatalf("unknown tool error = %+v, want -32601", rerr)
}
// A local tool has no device and must audit device "-".
if _, _, rerr = callLocal(t, s, "get_server_status", `{}`); rerr != nil {
t.Fatalf("get_server_status error = %+v", rerr)
}
recs := readAuditRecords(t, auditPath)
if len(recs) != 3 {
t.Fatalf("audit records = %d, want 3", len(recs))
}
ok := recs[0]
if ok["event"] != "mcp.tool.call" || ok["actor"] != "mcp" || ok["role"] != "admin" || ok["source"] != "mcp" {
t.Fatalf("identity fields = %v", ok)
}
if ok["tool"] != "terminal_exec" || ok["device"] != "1001" {
t.Fatalf("tool/device = %v/%v", ok["tool"], ok["device"])
}
if ok["ok"] != true || ok["code"].(float64) != 0 {
t.Fatalf("ok/code = %v/%v", ok["ok"], ok["code"])
}
if _, hasMS := ok["ms"]; !hasMS {
t.Fatal("missing ms")
}
args, _ := ok["args"].(string)
if !strings.Contains(args, "mysql (len=") {
t.Fatalf("args = %q, want first word + length", args)
}
if strings.Contains(args, "TopSecret") {
t.Fatalf("args leaked the command body: %q", args)
}
if res, _ := ok["result"].(string); !strings.Contains(res, "bytes") {
t.Fatalf("result = %q, want byte summary", res)
}
bad := recs[1]
if bad["tool"] != "nope" || bad["ok"] != false || bad["code"].(float64) != CodeMethodNotFound {
t.Fatalf("failed call record = %v", bad)
}
if bad["device"] != "-" {
t.Fatalf("unknown tool device = %v, want -", bad["device"])
}
if res, _ := bad["result"].(string); !strings.Contains(res, "unknown tool") {
t.Fatalf("failure result = %q", res)
}
local := recs[2]
if local["tool"] != "get_server_status" || local["device"] != "-" || local["ok"] != true {
t.Fatalf("local tool record = %v", local)
}
}
// A panicking handler must not take the connection down and must not be
// audited as a success.
func TestToolCallPanicAuditedAsFailure(t *testing.T) {
dir := t.TempDir()
auditPath := filepath.Join(dir, "audit.log")
log := logger.New(logger.Config{
Level: logger.LevelError,
File: filepath.Join(dir, "server.log"),
AuditFile: auditPath,
})
t.Cleanup(func() { _ = log.Close() })
s := New(Config{Token: testToken, Log: log})
s.handlers["terminal_exec"] = func(_ context.Context, _ json.RawMessage) (any, *rpcError) {
panic("boom")
}
if _, rerr := s.callTool(context.Background(), json.RawMessage(
`{"name":"terminal_exec","arguments":{"id":"1001","command":"dir"}}`)); rerr == nil ||
rerr.Code != CodeInternal {
t.Fatalf("panic call error = %+v, want -32000", rerr)
}
recs := readAuditRecords(t, auditPath)
if len(recs) != 1 {
t.Fatalf("audit records = %d, want 1", len(recs))
}
if recs[0]["ok"] != false || recs[0]["code"].(float64) != CodeInternal {
t.Fatalf("panic record = %v, want ok=false code=-32000", recs[0])
}
// The host lock must be free again despite the panic.
s.handlers["terminal_exec"] = func(_ context.Context, _ json.RawMessage) (any, *rpcError) {
return newToolResult("ok", nil), nil
}
if _, rerr := s.callTool(context.Background(), json.RawMessage(
`{"name":"terminal_exec","arguments":{"id":"1001"}}`)); rerr != nil {
t.Fatalf("call after panic error = %+v, want success", rerr)
}
}
func TestSummarizeArgsRedactsSensitiveValues(t *testing.T) {
got := summarizeArgs(json.RawMessage(`{
"id": "1001",
"command": "mysql -pTopSecret --batch",
"text": "hello secret",
"message": "msg secret",
"body": "{\"key\":\"secret\"}",
"headers": {"Authorization": "Bearer tok"},
"password": "pw"
}`))
for _, leak := range []string{"TopSecret", "hello secret", "msg secret", "Bearer tok", "pw"} {
if strings.Contains(got, leak) {
t.Fatalf("args leaked %q: %s", leak, got)
}
}
if !strings.Contains(got, "mysql (len=") {
t.Fatalf("command digest missing: %s", got)
}
if !strings.Contains(got, "redacted(") {
t.Fatalf("redaction marker missing: %s", got)
}
if len(got) > auditArgsMaxBytes {
t.Fatalf("digest = %d bytes, want <= %d", len(got), auditArgsMaxBytes)
}
// The ellipsis counts toward the cap.
long := summarizeArgs(json.RawMessage(`{"note":"` + strings.Repeat("a", 800) + `"}`))
if len(long) > auditArgsMaxBytes || !strings.HasSuffix(long, "…") {
t.Fatalf("truncated digest = %d bytes, tail %q", len(long), long[len(long)-3:])
}
}
+51 -4
View File
@@ -8,6 +8,7 @@ import (
"errors"
"io"
"net/http"
"runtime/debug"
"strings"
"time"
@@ -63,6 +64,12 @@ type Server struct {
log *logger.Logger
tools *toolSet
handlers map[string]toolFunc
// locks serialises device operations; sem bounds the global in-flight
// tools/call count. Both are non-blocking: contention is -32003, not a
// queue, so a slow call cannot pile up requests behind it (design §9).
locks *deviceLocks
sem chan struct{}
}
// New builds the endpoint. Zero-valued knobs fall back to the documented
@@ -92,6 +99,8 @@ func New(cfg Config) *Server {
log: cfg.Log,
tools: buildToolSet(toolsJSON),
handlers: make(map[string]toolFunc),
locks: newDeviceLocks(),
sem: make(chan struct{}, cfg.MaxConcurrency),
}
s.registerLocalTools()
return s
@@ -231,10 +240,11 @@ func (s *Server) initializeResult() initializeResult {
}
}
// callTool parses tools/call, enforces visibility, and hands the raw
// arguments to the handler. Readonly mode refuses hidden write tools with
// -32006 rather than pretending they do not exist.
func (s *Server) callTool(ctx context.Context, raw json.RawMessage) (any, *rpcError) {
// callTool parses tools/call, enforces visibility, takes the concurrency and
// device gates, then hands the raw arguments to the handler. Readonly mode
// refuses hidden write tools with -32006 rather than pretending they do not
// exist. Every call that names a tool is audited, including rejected ones.
func (s *Server) callTool(ctx context.Context, raw json.RawMessage) (result any, rerr *rpcError) {
if len(raw) == 0 || string(raw) == "null" {
return nil, errf(CodeInvalidParams, "tools/call requires params")
}
@@ -245,6 +255,24 @@ func (s *Server) callTool(ctx context.Context, raw json.RawMessage) (any, *rpcEr
if params.Name == "" {
return nil, errf(CodeInvalidParams, "tool name is required")
}
start := time.Now()
deviceID := ""
if !localReadTools[params.Name] {
deviceID = deviceIDFromArgs(params.Arguments)
}
defer func() {
// Convert a handler panic into -32000 instead of letting net/http drop
// the connection, and make sure the audit record says the call failed:
// without this the zero-valued rerr would be logged as success.
if p := recover(); p != nil {
s.log.Error("panic in MCP tool %s: %v\n%s", params.Name, p, debug.Stack())
result = nil
rerr = errf(CodeInternal, "internal error in tool %s", params.Name)
}
s.auditCall(params.Name, deviceID, params.Arguments, result, rerr, time.Since(start))
}()
if !s.tools.known(params.Name) {
return nil, errf(CodeMethodNotFound, "unknown tool: %s", params.Name)
}
@@ -257,6 +285,25 @@ func (s *Server) callTool(ctx context.Context, raw json.RawMessage) (any, *rpcEr
// a temporary state between milestones, not a client mistake.
return nil, errf(CodeInternal, "tool %s is not implemented by this server build", params.Name)
}
// Global slot first: a call that would be rejected for concurrency must
// not squat on a device lock while it fails.
select {
case s.sem <- struct{}{}:
defer func() { <-s.sem }()
default:
return nil, errf(CodeBusy, "Server busy: too many concurrent MCP calls (limit %d)",
s.cfg.MaxConcurrency)
}
if deviceID != "" {
held, acquired := s.locks.tryAcquire(deviceID, params.Name)
if !acquired {
return nil, errf(CodeBusy, "%s", busyMessage(held))
}
defer s.locks.release(deviceID)
}
return handler(ctx, params.Arguments)
}