Skip to content
Open
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
1,944 changes: 1,624 additions & 320 deletions api/agentmesh.pb.go

Large diffs are not rendered by default.

230 changes: 230 additions & 0 deletions api/agentmesh.proto
Original file line number Diff line number Diff line change
Expand Up @@ -1066,3 +1066,233 @@ message RevocationsResponse {
repeated string banned_peer_ids = 2;
}

// ============================================================================
// Generic Security Signals & Containment Contract (Issue #879)
// ============================================================================

// Direction of the caller when a security event or policy evaluation occurs.
enum SignalCallerDirection {
SIGNAL_CALLER_DIRECTION_UNSPECIFIED = 0;
// A local workload/agent process invoking the agentmesh-node sidecar.
LOCAL_WORKLOAD = 1;
// An external or remote peer sending traffic across the mesh network.
REMOTE_PEER = 2;
}

// Reason codes for policy evaluation denial.
enum PolicyDenialReason {
POLICY_DENIAL_REASON_UNSPECIFIED = 0;
// Denied by Biscuit Datalog authorization policy evaluation.
DATALOG_EVALUATION_DENIED = 1;
// Denied by TaskAuthorizationRule (tar_block) narrowing or operation constraints.
TASK_AUTHORIZATION_RULE_VIOLATION = 2;
// Blocked by an inspection filter (ModelArmor or ExtProc).
INSPECTION_FILTER_BLOCKED = 3;
// Caller does not possess the required PolicyRole.
ROLE_MISMATCH = 4;
// Caller credential or Biscuit has expired.
EXPIRED_CREDENTIAL = 5;
// Requested service name is not allowed by policy.
UNAUTHORIZED_SERVICE = 6;
// Requested HTTP method or path pattern is not permitted by HTTPGrant.
UNAUTHORIZED_PATH_OR_METHOD = 7;
}

// Emitted as CloudEvents type "agentmesh.policy.denied" when an authorization check,
// TAR rule narrowing, or inspection filter rejects a request.
message PolicyDeniedSignal {
// Direction of the caller: LOCAL_WORKLOAD vs REMOTE_PEER.
SignalCallerDirection direction = 1;
// Structured policy denial reason code.
PolicyDenialReason reason = 2;
// Human-readable detail or rejection explanation.
string detail = 3;
// Target service requested (e.g. "bigquery", "calculator-mcp").
string target_service = 4;
// Requested operation (e.g. HTTP method "POST" or MCP tool "execute").
string requested_operation = 5;
// Requested path or resource pattern (e.g. "/v1/projects/*").
string requested_resource = 6;
// Caller peer ID (if REMOTE_PEER or known).
string caller_peer_id = 7;
// Caller principal/subject from Biscuit or JWT.
string caller_subject = 8;
// Caller roles extracted from Biscuit authority/delegation blocks.
repeated string caller_roles = 9;
// Attested caller labels from Biscuit.
map<string, string> caller_labels = 10;
// Instant when policy denial occurred. Per AGENTS.md, MUST be named *_time.
google.protobuf.Timestamp event_time = 11;
}

// Reason codes for libp2p connection or stream gate refusals.
enum TransportRefusalReason {
TRANSPORT_REFUSAL_REASON_UNSPECIFIED = 0;
// Remote peer did not complete authentication within deadline.
PEER_UNAUTHENTICATED = 1;
// Remote peer attempted to access a router-only protocol without mesh:role:router.
NOT_ROUTER_ROLE = 2;
// Auth handshake wait timed out.
AUTH_DEADLINE_EXCEEDED = 3;
// Remote peer is in the banned/revocation set.
PEER_BANNED = 4;
// Protocol requested is not permitted for the peer's role.
PROTOCOL_UNAUTHORIZED = 5;
}

// Emitted as CloudEvents type "agentmesh.transport.refused" when the connection
// or stream auth gate (internal/node/auth_gate.go) rejects an incoming stream/peer.
message TransportRefusedSignal {
// Structured reason code for transport refusal.
TransportRefusalReason reason = 1;
// Human-readable detail message.
string detail = 2;
// Remote libp2p peer ID string.
string peer_id = 3;
// Remote multiaddr string (e.g. "/ip4/192.168.1.10/tcp/4001").
string remote_multiaddr = 4;
// Protocol ID requested (e.g. "/agentmesh/auth", "/libp2p-http").
string protocol_id = 5;
// Coalesced refusal count within the deduplication window (>= 1).
uint32 coalesced_count = 6;
// Timestamp of the first observed rejection in this coalescing window.
google.protobuf.Timestamp first_seen_time = 7;
// Timestamp of the most recent rejection. Per AGENTS.md, MUST be named *_time.
google.protobuf.Timestamp event_time = 8;
}

// Provenance/source of an identity revocation.
enum RevocationSource {
REVOCATION_SOURCE_UNSPECIFIED = 0;
// Administrative action on agentmesh-control-plane.
CONTROL_PLANE_ADMIN = 1;
// MeshEvent.BANNED received via gossip / SSE broadcast.
MESH_EVENT_BANNED_GOSSIP = 2;
// Reconciled during control-plane synchronization.
LOCAL_CONTROL_PLANE_SYNC = 3;
// Token refresh endpoint refused due to active ban.
TOKEN_REFRESH_REJECTION = 4;
}

// Emitted as CloudEvents type "agentmesh.identity.revoked" when a peer identity
// or Biscuit token is revoked or banned.
message IdentityRevokedSignal {
// Subject peer ID that has been revoked or banned.
string peer_id = 1;
// Source or trigger of the revocation.
RevocationSource source = 2;
// Revocation reason provided by administrator or policy.
string reason = 3;
// Hex-encoded Biscuit authority revocation IDs (RevocationIds()[0]).
repeated string revocation_ids = 4;
// Peer ID of the node or control plane emitting the revocation.
string issuer_peer_id = 5;
// Instant when the revocation occurred. Per AGENTS.md, MUST be named *_time.
google.protobuf.Timestamp event_time = 6;
}

// Reason codes for enrollment rejection.
enum EnrollmentRejectionReason {
ENROLLMENT_REJECTION_REASON_UNSPECIFIED = 0;
// Platform JWT token validation failed (signature, audience, issuer).
INVALID_JWT = 1;
// Bootstrap token has expired.
EXPIRED_BOOTSTRAP_TOKEN = 2;
// Bootstrap token max usage limit reached.
BOOTSTRAP_TOKEN_USAGE_EXCEEDED = 3;
// Requested labels failed policy attestation.
UNATTESTED_LABELS_REJECTED = 4;
// Proof of possession challenge signature is invalid.
INVALID_CHALLENGE_SIGNATURE = 5;
// Requested role is not permitted for the caller identity.
REQUESTED_ROLE_UNAUTHORIZED = 6;
// Peer is in the banned peer list.
PEER_PREVIOUSLY_BANNED = 7;
// Autonomous token recovery is disabled for the token or node.
AUTONOMOUS_RECOVERY_DISABLED = 8;
}

// Emitted as CloudEvents type "agentmesh.enrollment.rejected" when enrollment
// or autonomous token recovery is rejected on /enroll or /refresh.
message EnrollmentRejectedSignal {
// Peer ID attempting enrollment or recovery.
string peer_id = 1;
// Role requested in the enrollment attempt.
string requested_role = 2;
// Structured reason code for rejection.
EnrollmentRejectionReason reason = 3;
// Human-readable detail message.
string detail = 4;
// Bootstrap token ID used (if bootstrap enrollment).
string bootstrap_token_id = 5;
// Remote IP address or multiaddr of the enrollment requester.
string remote_address = 6;
// Labels submitted in the enrollment request.
map<string, string> submitted_labels = 7;
// True if this rejection occurred during an autonomous recovery attempt on /refresh.
bool is_autonomous_recovery = 8;
// Instant when rejection occurred. Per AGENTS.md, MUST be named *_time.
google.protobuf.Timestamp event_time = 9;
}

// SecuritySignalEvent is the CloudEvents 1.0 compliant envelope for dispatching
// security state transitions to external runtimes over HTTP or Unix sockets.
message SecuritySignalEvent {
// CloudEvents 'id': Unique event identifier (UUID v4).
string id = 1;
// CloudEvents 'source': URI identifying the emitting context (e.g. "urn:agentmesh:node:<peer_id>").
string source = 2;
// CloudEvents 'specversion': The CloudEvents specification version (always "1.0").
string spec_version = 3;
// CloudEvents 'type': Event type (e.g. "agentmesh.policy.denied").
string type = 4;
// CloudEvents 'time': Event generation instant. Per AGENTS.md, MUST be named *_time.
google.protobuf.Timestamp event_time = 5;
// CloudEvents 'datacontenttype': MIME type ("application/json" or "application/x-protobuf").
string data_content_type = 6;
// CloudEvents 'subject': Subject peer ID or identifier.
string subject = 7;

// Typed signal payload (mutually exclusive).
oneof data {
PolicyDeniedSignal policy_denied = 8;
TransportRefusedSignal transport_refused = 9;
IdentityRevokedSignal identity_revoked = 10;
EnrollmentRejectedSignal enrollment_rejected = 11;
}
}

// WebhookEndpointConfig defines a single outbound destination for security signals.
message WebhookEndpointConfig {
// Target URL: https://..., http://127.0.0.1:<port>, or unix:/path/to.sock.
string url = 1;
// File path to the shared secret for HMAC-SHA256 signing (X-AgentMesh-Signature).
// Per AGENTS.md secret hygiene, MUST be a file path, never an inline secret string.
string hmac_secret_path = 2;
// File path to CA certificate bundle for server TLS verification.
string ca_cert_path = 3;
// File path to client TLS certificate for mTLS authentication.
string client_cert_path = 4;
// File path to client TLS private key for mTLS authentication.
string client_key_path = 5;
// Per-dispatch HTTP request / socket write deadline.
google.protobuf.Duration timeout = 6;
// Maximum retry attempts for transient delivery failures (default: 3).
uint32 max_retries = 7;
// Filter list of event types to dispatch. If empty, all signals are sent.
repeated string event_types = 8;
}

// SecuritySignalsConfig configures out-of-band security signal dispatching.
message SecuritySignalsConfig {
// True if security signal dispatching is enabled.
bool enabled = 1;
// Destination endpoints.
repeated WebhookEndpointConfig endpoints = 2;
// Bounded ring-buffer queue capacity (default: 1024).
uint32 queue_capacity = 3;
// Window duration for coalescing repetitive events.
google.protobuf.Duration coalescing_window = 4;
}


4 changes: 3 additions & 1 deletion api/ingress_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,10 @@ import (
"crypto/rand"
"slices"
"testing"
"time"

"github.com/eclipse-biscuit/biscuit-go/v2"
"github.com/eclipse-biscuit/biscuit-go/v2/datalog"
"github.com/libp2p/go-libp2p/core/crypto"
"github.com/libp2p/go-libp2p/core/peer"
)
Expand Down Expand Up @@ -309,7 +311,7 @@ func TestIngressDatalogPolicyEvaluation(t *testing.T) {
}

check := func(svcType, svcName, mode string) bool {
auth, err := tok.Authorizer(pub)
auth, err := tok.Authorizer(pub, biscuit.WithWorldOptions(datalog.WithMaxDuration(5*time.Second)))
if err != nil {
t.Fatalf("Authorizer: %v", err)
}
Expand Down
25 changes: 23 additions & 2 deletions api/policy.go
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,29 @@ type NodeConfig struct {
// Labels is what this node is, attested at enrollment; Egress is what it
// demands of the peers it talks to. Adjacent because they are read
// together and mean opposite directions.
Labels map[string]string `yaml:"labels,omitempty"`
Egress Egress `yaml:"egress"`
Labels map[string]string `yaml:"labels,omitempty"`
Egress Egress `yaml:"egress"`
SecuritySignals SecuritySignalsConfigYAML `yaml:"security_signals,omitempty"`
}

// SecuritySignalsConfigYAML holds YAML configuration for out-of-band security containment webhooks.
type SecuritySignalsConfigYAML struct {
Enabled bool `yaml:"enabled"`
QueueCapacity int `yaml:"queue_capacity,omitempty"`
CoalescingWindow string `yaml:"coalescing_window,omitempty"`
Endpoints []WebhookEndpointConfigYAML `yaml:"endpoints,omitempty"`
}

// WebhookEndpointConfigYAML holds YAML configuration for an individual webhook endpoint.
type WebhookEndpointConfigYAML struct {
URL string `yaml:"url"`
HMACSecretPath string `yaml:"hmac_secret_path,omitempty"`
CACertPath string `yaml:"ca_cert_path,omitempty"`
ClientCertPath string `yaml:"client_cert_path,omitempty"`
ClientKeyPath string `yaml:"client_key_path,omitempty"`
Timeout string `yaml:"timeout,omitempty"`
MaxRetries uint32 `yaml:"max_retries,omitempty"`
EventTypes []string `yaml:"event_types,omitempty"`
}

// NodeConfigVersionV1Alpha1 is the only node config schema this build understands.
Expand Down
59 changes: 59 additions & 0 deletions cmd/agentmesh-node/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ import (
"time"

"github.com/google/agentmesh/api"
"github.com/google/agentmesh/internal/containment"
"github.com/google/agentmesh/internal/logging"
"github.com/google/agentmesh/internal/node"
"github.com/google/agentmesh/internal/pprofserver"
Expand Down Expand Up @@ -112,6 +113,17 @@ var (
secretsDirFlag string
controlPlaneSyncIntervalFlag time.Duration
cloudProviderFlag string

securityWebhookURLFlag string
securityWebhookHMACPathFlag string
securityWebhookCACertPathFlag string
securityWebhookClientCertFlag string
securityWebhookClientKeyFlag string
securityWebhookTimeoutFlag time.Duration
securityWebhookMaxRetriesFlag uint32
securityWebhookEventsFlag []string
securityWebhookQueueCapFlag int
securityWebhookCoalesceWinFlag time.Duration
)

var logger = golog.Logger("agentmesh-node-cli")
Expand Down Expand Up @@ -438,6 +450,36 @@ func main() {
logger.Fatalf("Invalid --router-prefer: %v", err)
}

var containmentCfg containment.Config
if nodeConfig != nil && nodeConfig.SecuritySignals != nil {
containmentCfg = *nodeConfig.SecuritySignals
}
if securityWebhookURLFlag != "" {
containmentCfg.Enabled = true
if securityWebhookQueueCapFlag > 0 {
containmentCfg.QueueCapacity = securityWebhookQueueCapFlag
}
if securityWebhookCoalesceWinFlag > 0 {
containmentCfg.CoalescingWindow = securityWebhookCoalesceWinFlag
}
ep := containment.EndpointConfig{
URL: securityWebhookURLFlag,
HMACSecretPath: securityWebhookHMACPathFlag,
CACertPath: securityWebhookCACertPathFlag,
ClientCertPath: securityWebhookClientCertFlag,
ClientKeyPath: securityWebhookClientKeyFlag,
Timeout: securityWebhookTimeoutFlag,
MaxRetries: securityWebhookMaxRetriesFlag,
EventTypes: securityWebhookEventsFlag,
}
if ep.HMACSecretPath == "" {
if envPath := strings.TrimSpace(os.Getenv("AGENTMESH_CONTAINMENT_HMAC_SECRET_PATH")); envPath != "" {
ep.HMACSecretPath = envPath
}
}
containmentCfg.Endpoints = append(containmentCfg.Endpoints, ep)
}

buildRuntimeNodeOptions := func(priv crypto.PrivKey, cpPub ed25519.PublicKey, rAddrs []multiaddr.Multiaddr) node.Options {
return node.Options{
PrivKey: priv,
Expand Down Expand Up @@ -468,6 +510,7 @@ func main() {
DiscoveryConcurrency: discoveryConcurrencyFlag,
BackendProbeTimeout: backendProbeTimeoutFlag,
SecretsDir: secretsDirFlag,
Containment: containmentCfg,
}
}

Expand Down Expand Up @@ -739,6 +782,11 @@ func main() {
}
}

var containmentCfg containment.Config
if nodeConfig != nil && nodeConfig.SecuritySignals != nil {
containmentCfg = *nodeConfig.SecuritySignals
}

priv := node.GetOrGenerateKey(store)
meshNode, err := node.NewAgentMeshNode(node.Options{
PrivKey: priv,
Expand All @@ -760,6 +808,7 @@ func main() {
RequiredRole: api.RoleNode,
ControlPlaneSyncInterval: controlPlaneSyncIntervalFlag,
BootstrapTokenPath: bootstrapTokenPathFlag,
Containment: containmentCfg,
})
if err != nil {
logger.Fatalf("Failed to initialize node for enrollment: %v", err)
Expand Down Expand Up @@ -892,6 +941,16 @@ func main() {
runCmd.Flags().DurationVar(&controlPlaneSyncIntervalFlag, "control-plane-sync-interval", node.DefaultControlPlaneSyncInterval, "How often signing keys, bans, router addresses and mesh policy are pulled from the control plane. Keep it well below the control plane's --key-grace-period; raise it on large meshes.")
runCmd.Flags().DurationVar(&backendProbeTimeoutFlag, "backend-probe-timeout", 0, "Timeout for probing a command-spawned service backend before advertising it (0 uses default 2s); raise this for backends with slower cold-start times")
runCmd.Flags().StringVar(&secretsDirFlag, "secrets-dir", node.DefaultSecretsDir, "Directory holding the credentials named by the control plane's egress destinations, one file per credential name")
runCmd.Flags().StringVar(&securityWebhookURLFlag, "security-webhook-url", "", "Out-of-band security containment webhook endpoint URL (https://..., http://127.0.0.1:port, or unix:/path/to.sock)")
runCmd.Flags().StringVar(&securityWebhookHMACPathFlag, "security-webhook-hmac-path", "", "Path to file containing shared secret for HMAC-SHA256 signature (or env AGENTMESH_CONTAINMENT_HMAC_SECRET)")
runCmd.Flags().StringVar(&securityWebhookCACertPathFlag, "security-webhook-ca-cert-path", "", "Path to CA certificate bundle for security webhook server verification")
runCmd.Flags().StringVar(&securityWebhookClientCertFlag, "security-webhook-client-cert-path", "", "Path to client TLS certificate for security webhook mTLS")
runCmd.Flags().StringVar(&securityWebhookClientKeyFlag, "security-webhook-client-key-path", "", "Path to client TLS private key for security webhook mTLS")
runCmd.Flags().DurationVar(&securityWebhookTimeoutFlag, "security-webhook-timeout", 500*time.Millisecond, "Per-dispatch HTTP/socket timeout for security webhook")
runCmd.Flags().Uint32Var(&securityWebhookMaxRetriesFlag, "security-webhook-max-retries", 3, "Maximum delivery retry attempts for security webhook")
runCmd.Flags().StringSliceVar(&securityWebhookEventsFlag, "security-webhook-events", nil, "Filter event types for security webhook (e.g. agentmesh.policy.denied); empty sends all")
runCmd.Flags().IntVar(&securityWebhookQueueCapFlag, "security-webhook-queue-capacity", 1024, "Bounded ring-buffer queue capacity for security webhook")
runCmd.Flags().DurationVar(&securityWebhookCoalesceWinFlag, "security-webhook-coalescing-window", time.Second, "Sliding deduplication window for security signals")
rootCmd.PersistentFlags().StringVar(&controlPlaneAddr, "control-plane", "", "Control plane URL")
rootCmd.PersistentFlags().BoolVar(&insecureControlPlaneFlag, "insecure-control-plane", false, "Accept a plaintext http:// control plane URL to a non-loopback host (whoever answers it becomes this node's trust root; only for networks you already trust)")
rootCmd.PersistentFlags().StringVar(&configFile, "config", node.DefaultConfigFile, "Path to agentmesh-node.yaml configuration file")
Expand Down
Loading
Loading