Skip to content
Sec-Gemini docs

Agent Scope & Security Policy Framework

The Sec-Gemini Security Policy Framework provides fine-grained, declarative control over what file system paths, network domains, shell commands, and tools are in scope or out of scope for Sec-Gemini agents and Bring Your Own Tool (BYOT) workstation connections.

Key Capabilities

Section titled “Key Capabilities”
  • 3-Tier Scope Hierarchy: Precedence resolution across Organization (Team), User, and Session policy profiles.
  • Mandatory Hard Deny: Organization and Team policies override lower-tier user or session policies to enforce non-bypassable enterprise security guardrails.
  • Safe Expression Evaluator: Safe AST-based expression engine supporting string matching, comparisons, set lookups, and boolean logic without arbitrary code execution risk.
  • BYOT Local Boundary Enforcement: Introspects local MCP servers to filter out-of-scope tools before startup and intercepts incoming CallTool requests locally on developer workstations.
  • Fail-Closed Design: Evaluation errors or malformed rule syntax fail closed with structured safety errors returned to the agent.

3-Tier Policy Hierarchy

Section titled “3-Tier Policy Hierarchy”

Policies are evaluated in a strict 3-tier hierarchy:

┌──────────────────────────────────────────────────────────┐
│ 1. Organization / Team Policy (Mandatory Hard Deny)      │  <-- Enterprise / Team Admin Policy
└────────────────────────────┬─────────────────────────────┘
                             │
┌────────────────────────────v─────────────────────────────┐
│ 2. User Personal Policy (~/.config/.../policy.toml)      │  <-- Developer Workstation Preferences
└────────────────────────────┬─────────────────────────────┘
                             │
┌────────────────────────────v─────────────────────────────┐
│ 3. Session Ephemeral Policy (Per-Session Scope Override) │  <-- Active Session Environment
└──────────────────────────────────────────────────────────┘

Precedence Rules

Section titled “Precedence Rules”
  1. Organization / Team (ORG): Highest priority. Any deny rule configured at the ORG tier cannot be overridden by user settings or session flags.
  2. User (USER): User workstation defaults defined in project .secgemini-policy.toml or ~/.config/sec-gemini/policy.toml.
  3. Session (SESSION): Ephemeral per-session overrides passed during SDK initialization.

Policy Configuration Schema

Section titled “Policy Configuration Schema”

Policies are serialized as TOML (or YAML) matching the Sec-Gemini policy specification:

[policy]
name = "workspace-security-profile"
version = "1.0"
mode = "enforce"         # Options: "enforce" | "audit" | "disabled"
default_action = "deny"  # Options: "allow" | "deny" | "ask"


# -------------------------------------------------------------------
# File Scoping Rules
# -------------------------------------------------------------------
[[policy.rules]]
name = "allow-workspace-files"
priority = 100
action = "allow"
reason = "Permit operations inside workspace root"
match = 'file.path.startsWith(workspace.root)'


[[policy.rules]]
name = "block-sensitive-credentials"
priority = 200
action = "deny"
reason = "Deny access to SSH keys, cloud credentials, and .env files"
match = 'file.path.contains(".ssh/") || file.path.contains(".aws/") || file.path.endsWith(".env")'


# -------------------------------------------------------------------
# Network Egress Control
# -------------------------------------------------------------------
[[policy.rules]]
name = "allow-approved-domains"
priority = 100
action = "allow"
reason = "Allow outgoing network traffic to approved endpoints"
match = 'http.host.endsWith(".google.com") || http.host == "pypi.org"'


# -------------------------------------------------------------------
# Shell & Tool Execution Guardrails
# -------------------------------------------------------------------
[[policy.rules]]
name = "confirm-destructive-commands"
priority = 150
action = "ask"
reason = "Destructive shell commands require explicit user confirmation"
match = 'mcp.tool == "run_command" && (mcp.args.CommandLine.contains("rm -rf") || mcp.args.CommandLine.contains("sudo"))'

Expression Context Attributes

Section titled “Expression Context Attributes”

Rule expressions are evaluated against standardized event context attributes:

Category Variable Attributes & Methods
Workspace workspace workspace.root, workspace.is_git_repo
FileSystem file file.path, file.canonical_path, file.action (read/write/edit), file.ext, file.size
Network http, dns http.host, http.url, http.scheme, http.port, http.method, dns.domain
MCP / Tools mcp mcp.server, mcp.tool, mcp.args
Process process process.cmd, process.args, process.cwd, process.env
Session session session.id, session.user, session.team_id

String Methods Supported

Section titled “String Methods Supported”
  • .startsWith(prefix) / .endsWith(suffix)
  • .contains(substring)
  • .matches(regex_pattern)
  • .lower() / .upper()

BYOT & Local Workstation Interception

Section titled “BYOT & Local Workstation Interception”

When using Bring Your Own Tool (BYOT) to connect local tools from your workstation to cloud agent sessions:

  1. Introspection Tool Pruning: ByotService evaluates active policies during tool discovery and filters out out-of-scope local tools before registration.
  2. Local gRPC Interception: ByotClient intercepts incoming CALL_TOOL gRPC jobs on your workstation and checks PolicyTracker before invoking local FastMCP tools.

Web UI Policy Editor & Cloud Execution

Section titled “Web UI Policy Editor & Cloud Execution”

Sessions initiated through the Sec-Gemini Web UI (cloud_services/ui) provide a dedicated Security Policy Manager and automatic policy enforcement:

  1. Web UI Policy Editor (/policies): Web portal to create, view, edit, name, and save security policy profiles.
  2. Automatic Policy Resolution: Upon prompt submission, api_hub checks request metadata (meta={"policy": "strict-scoping"}). If specified, PolicyManager resolves the named policy from Firestore and attaches the configuration to the execution payload.
  3. Cloud Worker Enforcement: The cloud agent container (job_worker) initializes the PolicyEngine with the resolved policy bundle to restrict cloud sandbox tool calls, file boundaries, network egress, and container execution.
  4. Interactive Web Approval Modals: Rules configured with action = "ask" trigger real-time modal dialogs in the Web UI interface for users to approve or reject sensitive tool calls.

Associating Policies with Sessions & Tightening Built-in Guardrails

Section titled “Associating Policies with Sessions & Tightening Built-in Guardrails”

Built-in policies are defined in sdk/python/sec_gemini/policy/default_policies.json and ship with a permissive default posture to ease adoption:

  • default-block-credentials (Priority 600, mandatory: true, default mode: audit)
  • default-workspace-boundary (Priority 500, mandatory: true, default mode: audit)
  • default-deny-google-network (Priority 700, opt-in, default mode: enforce, active_by_default: false)
  • default-allow (Priority 1, active_by_default: true, mode: enforce)
  • system-default-deny (Priority 0, immutable fallback DENY)

In audit mode, rule matches are recorded as non-terminal AUDIT_MATCH entries (PolicyDecision.audit_matches and structured policy_audit_match logs) without blocking execution or shadowing lower-priority enforce rules. You can tighten any built-in guardrail to enforce on a session:

# Tighten built-in guardrails to ENFORCE for a session
session.policies.enforce("default-block-credentials")
session.policies.enforce("default-workspace-boundary")


# Enable the opt-in Google network restriction
session.policies.enable("default-deny-google-network")

You can also associate a named policy profile with any prompt request across the SDK, TUI, or Web UI by supplying the policy name or ID in meta:

# Python SDK Example
session = client.create_session(
    prompt="Audit repo security",
    meta={"policy": "strict-scoping"}  # Associates named policy profile
)

In api_hub, PromptManager looks up "strict-scoping" in Firestore, binds the resolved PolicyConfig to the execution metadata, and passes it to job_worker for enforcement.

CLI Management & Testing Commands

Section titled “CLI Management & Testing Commands”

Use the sec-gemini policy CLI subcommands to validate rule syntax and perform dry-run tests:

Terminal window
# Validate policy file syntax and expressions:
sec-gemini policy validate .secgemini-policy.toml


# Dry-run test a file path or tool call against active rules:
sec-gemini policy check --file-path "/path/to/project/main.py"
sec-gemini policy check --mcp-tool "run_command"