Docs: link to a third-party SecurityAnalyzerBase implementation (ACGS rules) in the security guide?

未关闭
#1,035 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
1/5
预计耗时
1 小时以内
新手友好度
52/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
活跃
技术栈
python
领域
documentation

调研方向

Start with sdk/guides/security.mdx and read the “Custom Security Analyzer Implementation” section. Check the guide’s conventions for linking community packages and whether third-party examples belong here or in OpenHands/extensions; the issue asks maintainers to decide before a PR is opened. Done means the link’s placement and wording are agreed on.

由索引模型根据 Issue 内容生成。

描述

The SDK security guide (sdk/guides/security.mdx) shows how to write a custom analyzer by subclassing
SecurityAnalyzerBase ("Custom Security Analyzer Implementation"). I maintain a small community package that
does this, openhands-acgs (Apache-2.0, https://github.com/acgs-ai/openhands-acgs).
It rates each action with declarative ACGS rules:

  • ACGSSecurityAnalyzer.security_risk(action) returns HIGH when a blocking rule matches, when a rule asks for
    human review, or when the action cannot be evaluated, and LOW otherwise. analyze_action adds the verdict,
    the rule IDs and the reason as SecurityAnalysis.details, never argument values.
  • It is a pydantic model like the built-in analyzers, so it is saved and restored with persisted conversations.

Because an analyzer only rates risk, the package documents that it is a risk signal plus confirmation, not a
hard block
. With the default NeverConfirm() policy, a HIGH action still runs. The recommended setup is
therefore:

from openhands.sdk.security.confirmation_policy import ConfirmRisky
from openhands_acgs import ACGSSecurityAnalyzer, resolve_confirmation

analyzer = ACGSSecurityAnalyzer()
conversation.set_security_analyzer(analyzer)
conversation.set_confirmation_policy(ConfirmRisky())  # pause on HIGH

# when execution_status == WAITING_FOR_CONFIRMATION:
resolve_confirmation(conversation, analyzer, approve)  # rejects ACGS denials, asks `approve` otherwise
conversation.run()

resolve_confirmation calls reject_pending_actions when any pending action is denied. It is tested offline with
a real LocalConversation and TestLLM against openhands-sdk 1.54.0 and 1.59.0, on Python 3.12 to 3.14.

Question: would a one- or two-sentence link to it be welcome, for example at the end of "Custom Security
Analyzer Implementation"? Something like:

For a community example, see openhands-acgs, which rates actions
with ACGS rules and rejects denied actions while the conversation waits for confirmation.

If links to third-party packages do not belong in this guide, or should live in OpenHands/extensions instead,
that is fine. I would not open a PR before you say where, if anywhere, it fits. The package is not affiliated with
or endorsed by OpenHands.

主要语言
MDX
星标
19
派生
104
平均合并
2 天 12 小时
30 天内合并 PR
80

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 有 Pull Request 模板
  • 没有贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

OpenHands/docs 的其他 Issue

查看 OpenHands/docs 的全部 Issue

相似的 Issue

更多 Documentation Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。