feat: add governance policy framework for ungoverned call sites (OWASP Agentic Top 10)

[devin-ai-integration]

Summary

Addresses #5280 — security audit identified ungoverned call sites (subprocess, HTTP, tool invocations) lacking approval gates per OWASP Agentic Top 10.

This PR introduces a governance policy framework that lets users define allowlist/blocklist rules and custom validators for three categories:

• SubprocessPolicy — controls which subprocess commands agents may execute (ASI08)
• HttpPolicy — controls which domains/URLs may be contacted (ASI07)
• ToolPolicy — controls which tools agents may invoke (ASI02)

Policies are aggregated into GovernanceConfig, embedded in SecurityConfig, and enforced at:

• Agent._validate_docker_installation() (subprocess governance)
• execute_tool_and_check_finality() / aexecute_tool_and_check_finality() (tool governance)
• CrewAgentExecutor._execute_single_native_tool_call() (native tool governance)

Governance is permissive by default — no existing behavior changes unless the user explicitly configures policies.

42 new tests cover all policy types, serialization, SecurityConfig integration, and the agent/tool execution paths.

Review & Testing Checklist for Human

• Verify crew_agent_executor.py control flow: The hook/governance blocking logic was restructured (governance check → hook check → execution). Confirm the governance_blocked / hook_blocked / max_usage_reached branching is correct and doesn't skip hooks or tool execution unexpectedly. Note the result = result no-op on the governance-blocked branch.
• HttpPolicy is defined but not wired in: HttpPolicy and validate_http() exist but no actual HTTP call site (httpx, requests) is wrapped with governance checks yet. Decide if this is acceptable as a foundation or if at least one integration point is needed.
• Coverage of subprocess call sites: Only _validate_docker_installation is governed. The audit identified ~69 subprocess sites. Verify this is an acceptable starting point.
• custom_validator serialization: Custom validators are excluded from Pydantic serialization (exclude=True), so they won't survive to_dict()/from_dict() round-trips. Confirm this is acceptable.
• Run the full test suite (uv run pytest tests -vv) to verify no regressions beyond the new governance tests.

Notes

• The GovernanceError exception carries .category and .detail attributes for programmatic handling.
• Blocked tool calls return a ToolResult message (not an exception) to allow the agent to recover gracefully.
• hasattr(crew, "security_config") guards are used at integration points to handle cases where crew may be a mock or None.

Link to Devin session: https://app.devin.ai/sessions/64ab5aab34d140128f9dd718388da42f

---

Note

Medium Risk
Touches core agent/tool execution paths by adding pre-execution governance checks, which could block previously-allowed subprocess/tool calls when configured. Default policies are permissive, but control-flow changes in native tool execution and new serialization fields warrant review.

Overview
Introduces a security governance policy framework (SubprocessPolicy, HttpPolicy, ToolPolicy) aggregated under GovernanceConfig and embedded into SecurityConfig (including to_dict/from_dict support and public exports via crewai.security).

Enforces governance at key call sites: Agent._validate_docker_installation() now validates the docker info subprocess before running, and tool execution now checks validate_tool() before running tools in both the ReAct tool path (execute_tool_and_check_finality/aexecute_tool_and_check_finality) and native tool-calling (CrewAgentExecutor._execute_single_native_tool_call, skipping hooks when governance blocks).

Adds a comprehensive new test suite (tests/security/test_governance.py) covering policy behavior, serialization/integration with SecurityConfig, and enforcement in the agent subprocess and tool execution paths.

^{Reviewed by Cursor Bugbot for commit 27d5790. Bugbot is set up for automated code reviews on this repo. Configure here.}

[devin-ai-integration]

Prompt hidden (unlisted session)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

In general, to avoid incomplete URL substring sanitization issues, code should parse URLs and examine structured components (such as hostname) rather than using substring checks on the raw URL; tests should likewise assert on well-defined structured values or exact messages, instead of substring matches that look like domain checks.

In this case, the best fix without changing functionality is to replace the substring assertion with a more specific equality (or startswith) assertion against the exact message format we expect from GovernanceError. The goal of the test is simply to ensure the blocked domain appears in the error detail. Assuming HttpPolicy formats the message as something like "Domain 'evil.com' is blocked by policy", we can assert equality with that full string. This avoids generic substring searches that the analyzer flags, while still verifying that evil.com is present in the detail exactly as intended. Concretely, in lib/crewai/tests/security/test_governance.py, within TestHttpPolicy.test_governance_error_attributes, replace assert "evil.com" in error.detail with an assertion that error.detail equals (or starts with) the expected message string (for example, assert error.detail == "Domain 'evil.com' is blocked by policy"). No new imports or helpers are required.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 27d5790. Configure here.}

[cursor]

Subprocess command basename extraction fails on Windows paths

Medium Severity

The basename extraction command[0].rsplit("/", 1)[-1] only splits on forward slashes and won't correctly extract the command name from Windows-style paths (e.g., C:\Program Files\Docker\docker.exe). This means blocked_commands=["docker"] would fail to match on Windows, creating a blocklist bypass. Using os.path.basename would handle both Unix and Windows path separators correctly.

 

^{Reviewed by Cursor Bugbot for commit 27d5790. Configure here.}

[cursor]

Dead code no-op self-assignment in governance branch

Low Severity

The line result = result is a self-assignment no-op that does nothing. This dead code makes the control flow harder to understand. A pass statement or a bare comment would more clearly communicate the intent that the governance-blocked result was already set above.

 

^{Reviewed by Cursor Bugbot for commit 27d5790. Configure here.}