From f2cbb5fdc8a0d801d91bda6e5e87e2f9a453195e Mon Sep 17 00:00:00 2001 From: openhands Date: Mon, 8 Dec 2025 01:49:41 +0000 Subject: [PATCH] Add documentation for configurable security policy - Created comprehensive guide for customizing agent security policies - Explains default vs custom security policy usage - Includes example code and best practices - Supports OpenHands/software-agent-sdk PR #427 Co-authored-by: openhands --- sdk/guides/configurable-security-policy.mdx | 65 +++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 sdk/guides/configurable-security-policy.mdx diff --git a/sdk/guides/configurable-security-policy.mdx b/sdk/guides/configurable-security-policy.mdx new file mode 100644 index 00000000..c04b5729 --- /dev/null +++ b/sdk/guides/configurable-security-policy.mdx @@ -0,0 +1,65 @@ +--- +title: "Configurable Security Policy" +description: "Learn how to customize security policies for your OpenHands agents to match your organization's security requirements." +--- + +# Configurable Security Policy + +OpenHands agents use security policies to assess the risk level of their actions. By default, agents use a built-in security policy template, but you can customize this to match your organization's specific security requirements. + +## Overview + +Security policies define risk assessment guidelines that help agents evaluate the safety of their actions. They typically categorize actions into different risk levels (LOW, MEDIUM, HIGH) and provide specific rules for when to escalate risk assessments. + +## Default Security Policy + +By default, all agents use the built-in `security_policy.j2` template. This provides standard risk assessment guidelines for common operations. + +## Custom Security Policy + +You can provide your own security policy template by specifying the `security_policy_filename` parameter when creating an agent. This allows you to: + +- Define custom risk categories +- Add organization-specific security rules +- Customize risk escalation criteria +- Include domain-specific security considerations + +## Example + +```python icon="python" expandable examples/01_standalone_sdk/28_configurable_security_policy.py + +``` + +## Key Features + +### 1. Default Policy Usage +The example shows how agents automatically use the built-in security policy when no custom policy is specified. + +### 2. Custom Policy Creation +Demonstrates creating a custom security policy template with: +- Custom risk level definitions +- Organization-specific rules +- Tailored security guidelines + +### 3. Policy Application +Shows how to apply the custom policy using the `security_policy_filename` parameter. + +### 4. Policy Verification +Includes verification that the custom policy is properly embedded in the agent's system message. + +## Best Practices + +1. **Start with the default policy** and customize only what you need +2. **Test your custom policies** thoroughly before deploying +3. **Keep policies concise** but comprehensive +4. **Document your custom rules** clearly +5. **Review and update policies** regularly + +## Use Cases + +- **Enterprise environments** with specific compliance requirements +- **High-security applications** requiring stricter risk assessment +- **Domain-specific deployments** with unique security considerations +- **Multi-tenant systems** with varying security levels + +Custom security policies help ensure that your OpenHands agents operate within your organization's security boundaries while maintaining their effectiveness. \ No newline at end of file