Help us shape the future of Go! Take the 2026 Go Developer Survey

security

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 28, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package security provides helpers that apply security policies to agent and tool pods. All pods created by agent-orca must comply with the Kubernetes PodSecurityStandards "restricted" profile and are additionally hardened with Tetragon eBPF policies and per-run NetworkPolicies.

The restricted baseline can be *scoped-relaxed* for the agent container of an Agent via Spec.Runtime.SecurityContextOverride (e.g. to bring up a VPN tun device). The override applies only to the container named "agent" (never the model-router sidecar or tool/router pods) and is gated at admission by a validating webhook that requires the namespace label `agentorca.io/enable-privileged-pods: "true"` and an Agent-level GuardrailPolicyRef.

Index

Constants

View Source 
const (
	// LabelAgentRunName is the pod label used to associate a pod with its AgentRun.
	LabelAgentRunName = "agentorca.io/run"
	// LabelManagedBy is the standard managed-by label.
	LabelManagedBy = "app.kubernetes.io/managed-by"
	// ManagedByValue is the value for LabelManagedBy.
	ManagedByValue = "agent-orca"

	// LabelComponent identifies the role of a pod within a run (agent or router).
	// Only set when split-pod topology is enabled (Agent.spec.networkIsolation.splitPod=true).
	LabelComponent = "agentorca.io/component"
	// LabelComponentAgent is the LabelComponent value for the agent pod in split-pod topology.
	LabelComponentAgent = "agent"
	// LabelComponentRouter is the LabelComponent value for the router pod in split-pod topology.
	LabelComponentRouter = "router"
)
View Source 
const (

	// LabelEnablePrivilegedPods is the namespace label that opts a namespace into
	// allowing PodSecurityOverride on its agents. Admission of an Agent (or AgentRun
	// against such an Agent) whose runtime requests an override is rejected unless
	// the namespace carries this label set to "true".
	LabelEnablePrivilegedPods = "agentorca.io/enable-privileged-pods"
	// PrivilegedPodsAllowedValue is the only value the label may take.
	PrivilegedPodsAllowedValue = "true"

	// LabelEnableSandboxes is the namespace label that opts a namespace into
	// running agents with spec.runtime.sandbox, which gives the agent a shell and
	// lets it exec arbitrary binaries. Its only accepted value is "true".
	LabelEnableSandboxes = "agentorca.io/enable-sandboxes"

	// ModelRouterTokenAudience is the audience used for projected SA tokens.
	// The model-router validates tokens with this audience via TokenReview.
	ModelRouterTokenAudience = "agentorca/model-router"

	// UITokenAudience is the audience used by the UIProxy pod's projected SA token.
	// The operator validates requests from the proxy with this audience via TokenReview.
	UITokenAudience = "agentorca/ui"
)
View Source 
const LabelKBIngest = "agentorca.io/kb-mcp-ingest"

LabelKBIngest marks pods belonging to KnowledgeBase ingestion Jobs. The KnowledgeBase controller sets it on Job pods and selects it in the ingestion NetworkPolicy.

View Source 
const TracingPolicyKind = "TracingPolicyNamespaced"

TracingPolicyKind is the Kubernetes kind for namespaced Tetragon policies.

Variables

View Source 
var TetragonGVR = schema.GroupVersionResource{
	Group:    "cilium.io",
	Version:  "v1alpha1",
	Resource: "tracingpoliciesnamespaced",
}

TetragonGVR is the GroupVersionResource for Cilium Tetragon TracingPolicy.

Functions

func AgentSAName 

func AgentSAName(agentName string) string

AgentSAName returns the deterministic ServiceAccount name for a managed Agent SA. The SA is stable (Agent-scoped, not run-scoped) to support cloud IAM bindings.

func ApplyAzurePodLabel 

func ApplyAzurePodLabel(pod *corev1.Pod, provider CloudProvider)

ApplyAzurePodLabel adds the Azure Workload Identity label to a pod when running on AKS. The label triggers the Azure Identity webhook which injects the federated token.

func ApplyCloudAuthAnnotations 

func ApplyCloudAuthAnnotations(sa *corev1.ServiceAccount, cloudAuth *agentorcav1alpha1.CloudAuthSpec, provider CloudProvider)

ApplyCloudAuthAnnotations annotates the ServiceAccount with the cloud-provider-specific identity binding declared in the Agent's cloudAuth field. The caller is responsible for updating the SA via the Kubernetes API.

func BuildAgentPodNetworkPolicy 

func BuildAgentPodNetworkPolicy(
	run *agentorcav1alpha1.AgentRun,
	namespace string,
) *networkingv1.NetworkPolicy

BuildAgentPodNetworkPolicy constructs the NetworkPolicy for the agent pod in split-pod topology. The agent pod's egress is restricted to the router pod (ports 8080/8082) and DNS — it cannot open arbitrary outbound connections to the internet.

The PodSelector targets pods labeled agentorca.io/component=agent for this run.

func BuildDeploymentRole 

func BuildDeploymentRole(deploymentName, namespace string) *rbacv1.Role

BuildDeploymentRole constructs a Role scoped to an AgentDeployment for use by warm pods. It grants the same permissions as BuildRunRole but is stable across runs.

func BuildDeploymentRoleBinding 

func BuildDeploymentRoleBinding(deploymentName, saName, namespace string) *rbacv1.RoleBinding

BuildDeploymentRoleBinding constructs a RoleBinding that grants the deployment-scoped Role to the Agent's ServiceAccount, used by warm pods.

func BuildIngestNetworkPolicy added in v0.6.2 

func BuildIngestNetworkPolicy(
	kbName, namespace string,
	extraEgress []agentorcav1alpha1.EgressRule,
) *networkingv1.NetworkPolicy

BuildIngestNetworkPolicy constructs a NetworkPolicy for KnowledgeBase ingestion Job pods. It is additive — NetworkPolicy rules from multiple policies are unioned — so creating it is safe even in namespaces without default-deny policies, and required in namespaces that have them.

Allowed egress:

  • DNS (UDP/TCP 53)
  • Kubernetes API (443/6443) — the ingester reads source ConfigMaps
  • Same-namespace pods (Qdrant, MCP servers, in-cluster embedding providers)
  • HTTP/HTTPS (80/443) — URL sources, external embedding APIs, S3
  • Any extra egress rules from KnowledgeBase.spec.ingestion.networkEgress

All ingress is denied; ingestion Jobs never accept inbound connections.

func BuildManagedServiceAccount 

func BuildManagedServiceAccount(agentName, namespace string) *corev1.ServiceAccount

BuildManagedServiceAccount constructs the stable Agent SA managed by the operator.

func BuildNetworkPolicy 

func BuildNetworkPolicy(
	run *agentorcav1alpha1.AgentRun,
	namespace string,
	toolEgressRules []agentorcav1alpha1.EgressRule,
	stateRedisEnabled bool,
	hindsightURL string,
	operatorNamespace string,
) *networkingv1.NetworkPolicy

BuildNetworkPolicy constructs a per-run NetworkPolicy that:

  • Denies all ingress by default
  • Allows egress to the Kubernetes API server (for SA TokenReview)
  • Allows egress to all model provider endpoints declared in the selector
  • Allows egress to tool-specific endpoints declared in the Tool specs
  • Allows egress to Redis on port 6379 when stateRedisEnabled is true
  • Allows egress to the operator's internal API on port 8082 (always — required for built-in router ops)
  • Denies all other egress

func BuildRouterPodNetworkPolicy 

func BuildRouterPodNetworkPolicy(
	run *agentorcav1alpha1.AgentRun,
	namespace string,
	toolEgressRules []agentorcav1alpha1.EgressRule,
	stateRedisEnabled bool,
	hindsightURL string,
	operatorNamespace string,
) *networkingv1.NetworkPolicy

BuildRouterPodNetworkPolicy constructs the NetworkPolicy for the router pod in split-pod topology. It applies the same egress rules as BuildNetworkPolicy (provider HTTPS, K8s API, Redis, tools, DNS) and adds ingress from the agent pod on ports 8080/8082, plus the model-router metrics port (9091) from namespaces labeled metrics: enabled (Prometheus/Datadog).

The PodSelector targets pods labeled agentorca.io/component=router for this run, so the router and agent pods receive independent egress allowances.

func BuildRouterSandboxIngressPolicy added in v0.8.0 

func BuildRouterSandboxIngressPolicy(
	run *agentorcav1alpha1.AgentRun,
	namespace string,
	sandboxNamespace string,
	supervisorLabels map[string]string,
) *networkingv1.NetworkPolicy

BuildRouterSandboxIngressPolicy admits a run's sandbox supervisor to the router pod on ports 8080/8082. In sandbox mode the agent workload runs in the sandbox runtime's namespace and its outbound connections are opened by the supervisor pod, so the supervisor — not an agent pod — is the router's client.

The policy is ingress-only and additive to BuildRouterPodNetworkPolicy. supervisorLabels must identify exactly this run's supervisor (the runtime's per-sandbox ID label), so other sandboxes in the shared namespace stay out.

func BuildRunRole 

func BuildRunRole(run *agentorcav1alpha1.AgentRun) *rbacv1.Role

BuildRunRole constructs a minimal Role for a specific AgentRun. The role allows the agent pod to read its own AgentRun object and create events.

func BuildRunRoleBinding 

func BuildRunRoleBinding(run *agentorcav1alpha1.AgentRun, saName, namespace string) *rbacv1.RoleBinding

BuildRunRoleBinding constructs a RoleBinding that grants the per-run Role to the Agent's stable ServiceAccount. This is what scopes each run's access without requiring a new SA per run.

func BuildTracingPolicy 

func BuildTracingPolicy(runName, namespace string) *unstructured.Unstructured

BuildTracingPolicy returns an unstructured TracingPolicyNamespaced that blocks dangerous syscalls for agent pods identified by the given AgentRun name.

Blocked syscalls:

  • execve / execveat: prevents spawning arbitrary sub-processes
  • ptrace: prevents attaching to other processes
  • mount: prevents mounting additional filesystems
  • open_by_handle_at: prevents bypassing path-based access controls

If Tetragon is not installed in the cluster the controller skips creation and logs a warning. Tetragon is an optional dependency.

func DeploymentRoleBindingName 

func DeploymentRoleBindingName(deploymentName string) string

DeploymentRoleBindingName returns the deterministic RoleBinding name for a deployment-scoped binding.

func DeploymentRoleName 

func DeploymentRoleName(deploymentName string) string

DeploymentRoleName returns the deterministic Role name for a deployment-scoped RBAC Role. This role is used by warm pods, which are not scoped to a single run.

func EnforcePodSecurity 

func EnforcePodSecurity(pod *corev1.Pod, agentOverride *agentorcav1alpha1.PodSecurityOverride)

EnforcePodSecurity applies the restricted PodSecurityStandards profile to pod and injects the projected ServiceAccount token volume for model-router authentication, with one scoped exception: when agentOverride describes a PodSecurityOverride, it is applied to the container named "agent" only (mounting /dev/net/tun and relaxing the restricted baseline for that container). All other containers — including the model-router sidecar and any framework init containers — always receive the full restricted profile.

This is called for every AgentRun pod, every tool pod, and every AgentDeployment pod.

func IngestNetworkPolicyName added in v0.6.2 

func IngestNetworkPolicyName(kbName string) string

IngestNetworkPolicyName returns the NetworkPolicy name for a KnowledgeBase's ingestion Jobs.

func RunRoleBindingName 

func RunRoleBindingName(runName string) string

RunRoleBindingName returns the deterministic RoleBinding name for a per-run binding.

func RunRoleName 

func RunRoleName(runName string) string

RunRoleName returns the deterministic Role name for a per-run RBAC Role.

func SafeLabelValue 

func SafeLabelValue(s string) string

SafeLabelValue returns s unchanged if it fits within the 63-byte Kubernetes label value limit. Otherwise it truncates and appends a short hash suffix to keep the value unique and within bounds.

func TracingPolicyName 

func TracingPolicyName(runName string) string

TracingPolicyName returns the deterministic name for a run's TracingPolicy.

Types

type CloudProvider 

type CloudProvider string

CloudProvider identifies the detected or configured cloud environment. 

const (
	CloudProviderGCP   CloudProvider = "gcp"
	CloudProviderAWS   CloudProvider = "aws"
	CloudProviderAzure CloudProvider = "azure"
	CloudProviderNone  CloudProvider = "none"
)

func DetectCloudProvider 

func DetectCloudProvider(ctx context.Context, c client.Client) CloudProvider

DetectCloudProvider inspects node labels to determine the active cloud provider. Returns CloudProviderNone if detection fails or if the cluster is on-premises.

Source Files

View all Source files

Directories

Path Synopsis
Package oidc provides a small, testable wrapper around the OpenID Connect authorization-code flow on top of coreos/go-oidc and golang.org/x/oauth2.
 Package oidc provides a small, testable wrapper around the OpenID Connect authorization-code flow on top of coreos/go-oidc and golang.org/x/oauth2.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.