feat(security): add shell evasion guard

[gnipping]

Description

Adds ShellEvasionGuardian, a quote-aware pre-execution check for execute_shell_command that flags common shell obfuscation / evasion patterns (for example command substitution, ANSI-C / locale quoting and empty-quote flag tricks, backslash-escaped whitespace and shell operators, suspicious newlines / \r, #-comment quote desync, and quoted-newline + #-line patterns). Findings are produced through the existing Tool Guard pipeline (ToolGuardEngine runs this guardian alongside the default rule- and file-path guardians).

Related Issue: N/A (replace with Fixes #… / Relates to #… if you have one)

Security Considerations: Defense-in-depth only: scanning happens before the shell tool runs; severity and approval behavior follow existing Tool Guard / approval UX. This does not replace OS-level sandboxing or channel auth; misclassification remains possible for unusual but legitimate commands, so users may still need to review or approve per existing flows.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• Refactoring

Component(s) Affected

• Core / Backend (app, agents, config, providers, utils, local_models)
• Console (frontend web UI)
• Channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.)
• Skills
• CLI
• Documentation (website)
• Tests
• CI/CD
• Scripts / Deploy

Checklist

• I ran pre-commit run --all-files locally and it passes
• If pre-commit auto-fixed files, I committed those changes and reran checks
• I ran tests locally (pytest or as relevant) and they pass (please run and tick if you did)
• Documentation updated (if needed)
• Ready for review

Testing

1. Ensure Tool Guard is enabled (default / QWENPAW_TOOL_GUARD_ENABLED / config as usual).
2. Trigger an agent (or any path that calls ToolGuardEngine.guard) with tool execute_shell_command and a command string that should match one of the guardian checks, for example:
   • echo $(whoami) → command substitution finding
   • echo $'-n' → obfuscated-flag style finding
   • echo\ hello → backslash-escaped whitespace
   • true \; false → backslash before operator
   • A command containing an unquoted newline between two tokens → newline finding
3. Confirm the aggregated guard result includes findings from shell_evasion_guardian and that the existing approval / blocked-tool UX still behaves as before for other guardians.

Local Verification Evidence

pre-commit run --all-files
# Passed (mypy, black, flake8, pylint, prettier, etc.)

pytest

[github-actions]

Welcome to QwenPaw! 🐾

Hi @gnipping, this is your 18th Pull Request.

🙌 Join Developer Community

Thanks so much for your contribution! We'd love to invite you to join the official QwenPaw developer group! You can find the Discord and DingTalk group links under the "Developer Community" section on our docs page:
https://qwenpaw.agentscope.io/docs/community

We truly appreciate your enthusiasm—and look forward to your future contributions! 😊

We'll review your PR soon.

[Copilot]

Pull request overview

Adds a new Tool Guard guardian that performs quote-aware scanning of execute_shell_command parameters to detect shell obfuscation/evasion patterns before execution.

Changes:

• Introduces ShellEvasionGuardian with multiple heuristics (command substitution, obfuscated flags, escaped whitespace/operators, newline/comment desync patterns).
• Registers the new guardian in ToolGuardEngine’s default guardian set.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File	Description
src/qwenpaw/security/tool_guard/guardians/shell_evasion_guardian.py	New guardian implementation and helper functions for detecting shell evasion patterns.
src/qwenpaw/security/tool_guard/engine.py	Adds ShellEvasionGuardian to the default guardian initialization.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.