From 19d5f7059f45fda88a84232ea829e2624b9c7923 Mon Sep 17 00:00:00 2001 From: MK Date: Wed, 11 Mar 2026 03:01:44 -0400 Subject: [PATCH 1/2] docs: sync documentation with code-agent skill and recent changes - tools.md: add code-agent builtin tools section (bash_execute, file_read/write/edit/patch, glob/grep_search, directory_tree), registration groups, PathValidator - skills.md: add code-agent skill, update github skill (now script-backed with 8 tools and 6 scripts) - channels.md: add Telegram processing indicators (interim message after 15s, context isolation) - security/guardrails.md: add skill-specific guardrails (deny_commands/output/prompts/responses), PII validators (Luhn, SSN), outbound redaction behavior --- docs/channels.md | 10 +++++++ docs/security/guardrails.md | 54 +++++++++++++++++++++++++++++++++++-- docs/skills.md | 53 +++++++++++++++++++++++++++++++++++- docs/tools.md | 45 +++++++++++++++++++++++++++++++ 4 files changed, 159 insertions(+), 3 deletions(-) diff --git a/docs/channels.md b/docs/channels.md index 31dca79..20272b8 100644 --- a/docs/channels.md +++ b/docs/channels.md @@ -103,6 +103,16 @@ When the Slack adapter receives a message: This gives users visual feedback that their message is being processed, especially for long-running research queries. +### Telegram Processing Indicators + +The Telegram adapter mirrors Slack's processing feedback: + +1. A typing indicator ("typing...") is sent immediately and refreshed every 4 seconds +2. If the handler takes longer than 15 seconds, an interim message is posted: _"Working on it — I'll send the result when ready."_ +3. The typing indicator stops when the response is ready + +**Context isolation:** Each handler goroutine runs with an independent context (10-minute timeout), detached from the polling loop. This prevents in-flight tasks from being cancelled if the polling context is interrupted during server restarts or errors. + ## Configuration ### Slack (`slack-config.yaml`) diff --git a/docs/security/guardrails.md b/docs/security/guardrails.md index e67a960..38a6107 100644 --- a/docs/security/guardrails.md +++ b/docs/security/guardrails.md @@ -9,7 +9,7 @@ The guardrail engine checks inbound and outbound messages against configurable p | Guardrail | Direction | Description | |-----------|-----------|-------------| | `content_filter` | Inbound + Outbound | Blocks messages containing configured blocked words | -| `no_pii` | Outbound | Detects email addresses, phone numbers, and SSNs via regex | +| `no_pii` | Outbound | Detects email, phone, SSNs (with structural validation), and credit cards (with Luhn check) | | `jailbreak_protection` | Inbound | Detects common jailbreak phrases ("ignore previous instructions", etc.) | | `no_secrets` | Outbound | Detects API keys, tokens, and private keys (OpenAI, Anthropic, AWS, GitHub, Slack, Telegram, etc.) | @@ -17,9 +17,24 @@ The guardrail engine checks inbound and outbound messages against configurable p | Mode | Behavior | |------|----------| -| `enforce` | Blocks violating messages, returns error to caller | +| `enforce` | Blocks violating inbound messages; **redacts** outbound messages (see below) | | `warn` | Logs violation, allows message to pass | +### Outbound Redaction + +Outbound messages (from the agent to the user) are always **redacted** rather than blocked, even in `enforce` mode. Blocking would discard a potentially useful agent response (e.g., code analysis) over a false positive from broad PII/secret patterns matching source code. Matched content is replaced with `[REDACTED]` and a warning is logged. + +### PII Validators + +To reduce false positives, PII patterns use structural validators beyond simple regex: + +| Pattern | Validator | What it checks | +|---------|-----------|---------------| +| SSN | `validateSSN` | Rejects area=000/666/900+, group=00, serial=0000, all-same digits, known test SSNs | +| Credit card | `validateLuhn` | Luhn checksum validation, 13-19 digit length check | +| Email | — | Regex only | +| Phone | — | Regex only (area code 2-9, separators required) | + ## Configuration Guardrails are defined in the policy scaffold, loaded from `policy-scaffold.json` or generated during `forge build`. @@ -110,6 +125,41 @@ Additionally, `cmd.Dir` is set to `workDir` so relative paths in subprocess exec | `jq '.' /tmp/data.json` | Allowed — system path outside `$HOME` | | `ls ./data/` | Allowed — within workDir | +## Skill-Specific Guardrails + +Skills can declare domain-specific guardrail rules in their SKILL.md frontmatter under `metadata.forge.guardrails`. These are enforced by a separate `SkillGuardrailEngine` that complements the global guardrails. + +```yaml +metadata: + forge: + guardrails: + deny_commands: + - pattern: "rm\\s+-rf\\s+/" + message: "Destructive filesystem operations are not allowed" + deny_output: + - pattern: "password:\\s*\\S+" + action: redact + deny_prompts: + - pattern: "what (tools|binaries|commands) (are|do you have)" + message: "I can help with specific tasks — just describe what you need." + deny_responses: + - pattern: "(?:^|\\n)\\s*[-*]\\s*\\S+.*\\n(\\s*[-*]\\s*\\S+.*\\n){3,}" + message: "I can help with specific tasks. What would you like me to do?" +``` + +### Filter Types + +| Filter | Applied When | Match Target | Behavior | +|--------|-------------|--------------|----------| +| `deny_commands` | Before tool execution | `"binary arg1 arg2 ..."` command line | Blocks execution, returns custom error to LLM | +| `deny_output` | After tool execution | Tool output text | `block`: hides result; `redact`: replaces matches with `[BLOCKED BY POLICY]` | +| `deny_prompts` | Before LLM receives input | User message text (case-insensitive) | Rejects message with custom error | +| `deny_responses` | After LLM generates output | LLM response text (case-insensitive) | Replaces response with custom message | + +### Aggregation + +When multiple skills are loaded, their guardrail rules are **merged** (deduplicated by pattern). The aggregated rules are compiled into regex once during agent initialization and reused for all subsequent checks. + ## Audit Events Guardrail evaluations are logged as structured audit events: diff --git a/docs/skills.md b/docs/skills.md index d74eaaf..70fbd45 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -163,7 +163,8 @@ forge skills list --tags kubernetes,incident-response | Skill | Icon | Category | Description | Scripts | |-------|------|----------|-------------|---------| -| `github` | 🐙 | developer | Create issues, PRs, and query repositories | — (binary-backed) | +| `github` | 🐙 | developer | Clone repos, create issues/PRs, and manage git workflows | `github-clone.sh`, `github-checkout.sh`, `github-commit.sh`, `github-push.sh`, `github-create-pr.sh`, `github-status.sh` | +| `code-agent` | 🤖 | developer | Autonomous code generation, modification, and project scaffolding | — (builtin tools) | | `weather` | 🌤️ | utilities | Get weather data for a location | — (binary-backed) | | `tavily-search` | 🔍 | research | Search the web using Tavily AI search API | `tavily-search.sh` | | `tavily-research` | 🔬 | research | Deep multi-source research via Tavily API | `tavily-research.sh`, `tavily-research-poll.sh` | @@ -356,6 +357,56 @@ This registers three tools: Requires: `jq`. Egress: `cdn.tailwindcss.com`, `esm.sh`. +### GitHub Skill + +The `github` skill provides a complete git + GitHub workflow through script-backed tools: + +```bash +forge skills add github +``` + +This registers eight tools: + +| Tool | Purpose | +|------|---------| +| `github_clone` | Clone a repository and create a feature branch | +| `github_checkout` | Switch to or create a branch | +| `github_status` | Show git status for a cloned project | +| `github_commit` | Stage and commit changes | +| `github_push` | Push a feature branch to the remote | +| `github_create_pr` | Create a pull request | +| `github_create_issue` | Create a GitHub issue | +| `github_list_issues` | List open issues for a repository | + +**Workflow:** Clone → explore → edit → status → commit → push → create PR. The skill's system prompt enforces this sequence and prevents raw `git` commands via `cli_execute`. + +Requires: `gh`, `git`, `jq`. Optional: `GH_TOKEN`. Egress: `api.github.com`, `github.com`. + +### Code-Agent Skill + +The `code-agent` skill enables autonomous code generation and modification using [builtin code-agent tools](tools.md#code-agent-tools): + +```bash +forge skills add code-agent +``` + +This registers eight tools: + +| Tool | Purpose | +|------|---------| +| `code_agent_scaffold` | Bootstrap a new project (Vite, Express, FastAPI, Go, Spring Boot, etc.) | +| `code_agent_write` | Create or update files | +| `code_agent_edit` | Surgical text replacement in existing files | +| `code_agent_read` | Read a file or list directory contents | +| `code_agent_run` | Install dependencies, start a server, open a browser | +| `grep_search` | Search file contents by regex | +| `glob_search` | Find files by name pattern | +| `directory_tree` | Show project directory tree | + +The skill uses **denied tools** (`bash_execute`, `file_write`, `file_edit`, `file_patch`, `file_read`, `schedule_*`) to ensure the LLM uses the skill's own tool wrappers instead of raw builtins. All file operations are confined to the agent's working directory via `PathValidator`. + +Requires: `bash`, `jq`. Egress: `registry.npmjs.org`, `cdn.tailwindcss.com`, `pypi.org`, `files.pythonhosted.org`, `proxy.golang.org`, `sum.golang.org`, `storage.googleapis.com`, `repo.maven.apache.org`, `repo1.maven.org`. + ## Skill Instructions in System Prompt Forge injects the **full body** of each skill's SKILL.md into the LLM system prompt. This means all detailed operational instructions — triage steps, detection heuristics, output structure, safety constraints — are directly available in the LLM's context without requiring an extra `read_skill` tool call. diff --git a/docs/tools.md b/docs/tools.md index 4856b87..817e55e 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -36,6 +36,51 @@ Tools are capabilities that an LLM agent can invoke during execution. Forge prov Register all builtins with `builtins.RegisterAll(registry)`. +## Code-Agent Tools + +When the `code-agent` skill is active, Forge registers additional tools for autonomous code generation and modification. These tools are **not** registered by default — they are conditionally added when the skill requires them. + +All code-agent tools use a `PathValidator` that confines resolved paths within the agent's working directory, preventing directory traversal attacks. + +| Tool | Description | +|------|-------------| +| `bash_execute` | Execute bash commands with pipes, redirection, and shell features | +| `file_read` | Read file contents with optional line offset/limit, or list directory entries | +| `file_write` | Create or overwrite files in the project directory | +| `file_edit` | Edit files by exact string matching with unified diff output | +| `file_patch` | Batch file operations (add, update, delete, move) in a single call | +| `glob_search` | Find files by glob pattern (e.g., `**/*.go`), sorted by modification time | +| `grep_search` | Search file contents with regex; uses `rg` if available, falls back to Go | +| `directory_tree` | Display tree-formatted directory listing (default max depth: 3) | + +### Registration Groups + +Code-agent tools are registered in layered groups, allowing skills to request only the capabilities they need: + +| Group | Tools | Purpose | +|-------|-------|---------| +| `CodeAgentSearchTools` | `grep_search`, `glob_search`, `directory_tree` | Read-only exploration | +| `CodeAgentReadTools` | `file_read` + search tools | Safe reading | +| `CodeAgentWriteTools` | `file_write`, `file_edit`, `file_patch`, `bash_execute` | Modification + execution | +| `CodeAgentTools` | All read + write tools | Full code-agent capability | + +### bash_execute Security + +| Layer | Detail | +|-------|--------| +| **Dangerous command denylist** | Blocks `rm -rf /`, `mkfs`, `dd`, fork bombs, and similar destructive patterns | +| **sudo/su blocked** | Privilege escalation prefixes are rejected | +| **Timeout** | Default 120s, configurable per invocation | +| **Output cap** | Maximum 1MB output to prevent memory exhaustion | + +### Path Validation + +All file tools use `PathValidator` (from `pathutil.go`): + +- All resolved paths must stay within the configured `workDir` +- Directory traversal via `..` is caught after symlink resolution +- Standard directories are excluded from search: `.git`, `node_modules`, `vendor`, `__pycache__`, `.venv`, `dist`, `build` + ## Adapter Tools | Adapter | Description | From 3607b88afd1dbd8a4deec7d69563115d44785081 Mon Sep 17 00:00:00 2001 From: MK Date: Wed, 11 Mar 2026 03:14:15 -0400 Subject: [PATCH 2/2] docs: update README title to include OpenClaw branding --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cfce007..4c59e3b 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Forge — Secure, Portable AI Agent Runtime +# Forge — OpenClaw for Enterprise: A Secure, Portable AI Agent Runtime Build, run, and deploy AI agents from a single `SKILL.md` file. Secure by default. Runs anywhere — local, container, cloud, air-gapped.