Agent Soul System

• Outcome: Review
• Latest audit: Sep 16, 2026 · 5:07 AM UTC
• Version: 1.0.0

Overview

This skill mostly matches its stated purpose, but it writes lasting agent personality files with a hardcoded reporting hierarchy and unsafe path handling.

Review the generated SOUL.md before letting agents use it. Replace the hardcoded superior/reporting fields with your own hierarchy, and avoid passing untrusted or path-like names to soul-create.py until path validation is added.

A.I.G

Vulnerability Patterns

• Skill Instruction Hijacking: Alters the agent's session goals or safety constraints when the skill loads
• Insecure Skill Coding Practices: Finds exploitable flaws such as hardcoded secrets or command injection
• Agent Memory Poisoning: Writes attacker-controlled rules into memory that affect later sessions
• Remote Payload Retrieval and Execution: Fetches external code whose behavior can change after review
• Embedded Malicious Code: Ships malicious scripts inside the skill and executes them locally

Findings (2)

T01 · Skill Instruction Hijacking

Error

• Location: scripts/soul-create.py:26

Finding

Hardcoded authority hierarchy redirects persistent agent behavior

Content

View full analysis

Vulnerability Details

File Location: references/collaboration-protocol.md:24-26, 45-49; scripts/soul-create.py:26-30
Vulnerability Type: Persistent redirection of agent instructions and reporting
Risk Level: High

Vulnerable Code

references/collaboration-protocol.md:24-26:

markdown

- Adam 只与小咪对话
- 所有 Agent 通过小咪接收指令和上报结果
- 小咪是唯一的"对外接口"

references/collaboration-protocol.md:45-49:

markdown

## 与上级的协作协议
- 直接上级：小咪
- 日常汇报：每5分钟/每小时/完成后
- 升级触发：[什么情况下需要上报]
- 决策权限：[可以自主决定的范围]

scripts/soul-create.py:26-30:

python

## 与上级的协作协议
- 直接上级：小咪
- 日常汇报：完成后/每小时/实时
- 升级触发：[什么情况下需要上报]
- 决策权限：[可以自主决定的范围]

Technical Analysis

The skill is presented as a reusable system for creating agent personality files, but it embeds a specific authority hierarchy into both its collaboration instructions and every generated SOUL.md file. The generated configuration designates a named agent as the direct superior and instructs agents to route instructions and reports through that identity.

These are not neutral formatting defaults. According to the skill documentation, SOUL.md defines an agent's personality, principles, responsibilities, and collaboration behavior. If the surrounding agent platform loads this file as persistent configuration, the hardcoded rules can continue influencing later sessions. The user is not required to select or confirm the named superior before the behavior-changing file is written.

Although the behavior also has persistence characteristics, the best matching classification is instruction hijacking because the primary mechanism is the insertion of unauthorized authority and communication instructions into agent configuration.

Attack Path

1. A user installs the skill as a generic personality-management utility.
2. The user follows the documented workflow and runs soul-create.py with an agent name.
3. The script writes a SOUL.md file co ...[truncated 1163 chars]

Remediation

View remediation

Remediation Suggestions

1. Remove all hardcoded personal identities, superior names, reporting routes, and authority relationships from templates and reference material.
2. Default new agents to having no superior or external reporting route.
3. Require the user to supply hierarchy values explicitly through named command-line options or an interactive setup process.
4. Display the complete collaboration configuration and require confirmation before writing behavior-changing rules.
5. Clearly distinguish optional examples from active template content. Example identities must never be copied automatically into generated files.
6. Add validation that rejects unresolved placeholders and prevents the skill from silently creating communication or authority relationships.
7. Document that generated files may persistently affect agent behavior and should be reviewed before activation.
8. Add tests confirming that a default invocation does not designate any person or agent as an instruction source, report recipient, or superior.

T09 · Insecure Skill Coding Practices

Warning

• Location: scripts/soul-create.py:37

Finding

Unvalidated agent name permits path traversal and arbitrary SOUL.md placement

Content

View full analysis

Vulnerability Details

File Location: scripts/soul-create.py:37-52
Vulnerability Type: Path traversal and unsafe file overwrite
Risk Level: Medium

Vulnerable Code

python

name = sys.argv[1]
path = os.path.join(AGENTS_DIR, name)
soul = os.path.join(path, "SOUL.md")

if os.path.exists(soul):
    print(f"⚠️ {name} 已有 SOUL.md，要覆盖吗？(y/n)")
    if input().lower() != 'y':
        sys.exit(0)

os.makedirs(path, exist_ok=True)
with open(soul, 'w') as f:
    f.write(TEMPLATE.format(name=name))

Technical Analysis

The script accepts sys.argv[1] as an untrusted agent name and uses it directly as a filesystem path component. It does not restrict the value to a simple identifier, normalize and verify the resulting path, or ensure that the destination remains under ~/.openclaw/agents.

Python's os.path.join does not provide containment enforcement:

• A value containing .. components can traverse out of the intended directory.
• An absolute path replaces the preceding base path.
• Existing symbolic links in the destination path can redirect file operations elsewhere.

After constructing the unsafe path, the script creates directories and opens SOUL.md in write mode. Write mode truncates an existing file after the user answers the overwrite prompt. The operation follows filesystem links and is performed with the privileges of the user running the script.

Attack Path

1. An attacker or untrusted automation controls the agent-name argument.
2. The attacker supplies an absolute path or traversal value, such as /attacker/chosen/location or ../../chosen/location.
3. os.path.join(AGENTS_DIR, name) resolves to a location outside AGENTS_DIR.
4. os.makedirs(path, exist_ok=True) creates the attacker-selected directory structure if permissions allow.
5. The script opens <attacker-selected-location>/SOUL.md in write mode.
6. If the file does not exist, it is created witho ...[truncated 968 chars]

Remediation

View remediation

Remediation Suggestions

1. Restrict agent names to a conservative identifier format, such as ^[A-Za-z0-9_-]+$.
2. Explicitly reject absolute paths, path separators, . components, and .. components.
3. Resolve the base and destination directories with os.path.realpath or pathlib.Path.resolve.
4. Verify containment using os.path.commonpath, ensuring the resolved destination remains strictly beneath the resolved agent base directory.
5. Reject destinations containing symbolic links, or use directory-file-descriptor operations and no-follow semantics where supported.
6. Create new files exclusively with mode x by default so existing files cannot be silently truncated.
7. Require an explicit --overwrite option rather than relying only on an interactive prompt.
8. Apply restrictive permissions to newly created configuration files where appropriate.
9. Add tests for absolute paths, nested traversal, mixed separators, symbolic-link redirection, and existing-file overwrite behavior.

A safe containment check should follow this pattern:

python

import re
from pathlib import Path

if not re.fullmatch(r"[A-Za-z0-9_-]+", name):
    raise ValueError("Invalid agent name")

base = Path(AGENTS_DIR).resolve()
path = (base / name).resolve()

if path.parent != base:
    raise ValueError("Agent path escapes the configured directory")

soul = path / "SOUL.md"

SkillSpector

Vulnerability Patterns

• Prompt Injection: Instruction Override, Hidden Instructions, Exfiltration Commands
• Data Exfiltration: External Transmission, Env Variable Harvesting, File System Enumeration
• Rogue Agent: Self-Modification, Session Persistence
• MCP Least Privilege: Underdeclared Capability, Wildcard Permission, Missing Permission Declaration
• MCP Tool Poisoning: Hidden Instructions, Unicode Deception, Parameter Description Injection

Findings (13)

Tp4

High

• Category: MCP Tool Poisoning
• Confidence: 96% confidence

Finding

The declared description presents a broad capability set centered on creating, managing, validating, and generating SOUL.md personality files for multi-agent systems. The supplied code does not implement those functions. Instead, it only reads from a fixed local directory (~/.openclaw/agents), lists agent folders, checks for SOUL.md existence, reports file size, and heuristically displays a personality-related line. While this is loosely related to auditing existing soul files, the primary purpose is materially narrower than declared, so the description does not accurately represent the actual behavior.

Content

No source excerpt is available for this finding.

Undeclared Tool Scope

Medium

• Category: MCP Least Privilege
• Confidence: 94% confidence

Finding

The skill advertises commands that read and write files under ~/.openclaw/agents/ but does not declare any tool or permission scope. That creates an authorization ambiguity where an agent may invoke filesystem-capable behavior without explicit least-privilege boundaries or user visibility into what paths may be accessed or modified.

Content

No source excerpt is available for this finding.

Natural-Language Policy Violations

Medium

• Category: Not specified by scanner
• Confidence: 87% confidence

Finding

The directory structure annotations and the SOUL.md template that follows are written partly in Chinese, and the template itself specifies section headings and content in Chinese. Because the file does not state that the skill is China-specific or give users an option to use another language, it implicitly enforces a locale/language preference.

Content

No source excerpt is available for this finding.

Natural-Language Policy Violations

Medium

• Category: Not specified by scanner
• Confidence: 93% confidence

Finding

The template defines required headings such as '人格', '核心特质', '说话风格', and other Chinese labels, which functions as a language requirement for generated content. Under the policy, forcing a specific language is a violation unless the skill offers a choice or clearly documents a justified locale constraint.

Content

No source excerpt is available for this finding.

Session Persistence

Medium

• Category: Rogue Agent
• Confidence: 71% confidence

Finding

The skill is designed to create and maintain persistent identity/personality files under ~/.openclaw/agents/, which can outlive a single session and influence future agent behavior. Persistent persona/configuration state is security-relevant because unauthorized or unreviewed modifications can steer later interactions, change reporting/escalation rules, or embed harmful instructions in long-lived agent metadata.

Content

Scanner excerpt · SKILL.md (reported line 60)May include surrounding context.

md

# Validate all agents have SOUL.md
python3 ~/.openclaw/workspace/skills/agent-soul-system/scripts/soul-check.py

# Create a new agent with SOUL.md template
python3 ~/.openclaw/workspace/skills/agent-soul-system/scripts/soul-create.py [agent-name]

# List all agents and their souls

Natural-Language Policy Violations

Medium

• Category: Not specified by scanner
• Confidence: 88% confidence

Finding

The collaboration rules and required SOUL.md fields are written as mandatory Chinese-language protocol content, including the named sole external interface '小咪' and required section labels. There is no indication that users or agents may choose another language, nor any documented region-specific reason for the language restriction.

Content

No source excerpt is available for this finding.

Natural-Language Policy Violations

Medium

• Category: Not specified by scanner
• Confidence: 92% confidence

Finding

The template’s section headings and placeholder content are entirely in Chinese, which semantically instructs skill authors to produce the SOUL file in a specific language. Because the file does not offer an opt-in, alternative locale, or justification for a Chinese-only requirement, it conflicts with the language/locale policy criteria.

Content

No source excerpt is available for this finding.

Natural-Language Policy Violations

Medium

• Category: Not specified by scanner
• Confidence: 91% confidence

Finding

This code enforces Chinese section headers such as "人格" and emits status messages in Chinese, which effectively requires a specific language/locale for successful use. The policy allows locale constraints only when users are given a choice or the restriction is clearly documented and justified, which is not present in this file.

Content

No source excerpt is available for this finding.

Session Persistence

Medium

• Category: Rogue Agent
• Confidence: 60% confidence

Finding

Skill establishes unauthorized persistence across sessions via cron jobs, startup scripts, or state files. Session persistence allows an attacker to maintain access beyond the current interaction.

Content

Scanner excerpt · scripts/soul-create.py (reported line 2)May include surrounding context.

python

#!/usr/bin/env python3
"""Create a new agent with SOUL.md template."""
import os, sys

AGENTS_DIR = os.path.expanduser("~/.openclaw/agents")

Natural-Language Policy Violations

Medium

• Category: Not specified by scanner
• Confidence: 95% confidence

Finding

This code generates a SOUL.md template whose section headings and guidance are entirely in Chinese, effectively imposing a specific language on downstream skill content. There is no user opt-in, locale selection, or documented region-specific justification, which matches the language/locale policy violation criteria.

Content

No source excerpt is available for this finding.

Natural-Language Policy Violations

Low

• Category: Not specified by scanner
• Confidence: 95% confidence

Finding

This markdown file switches from English to Chinese for the substantive content, including headings, table columns, and persona descriptions. Because the file does not offer a user language choice or explain that it is intentionally region-specific, it may violate a language/locale policy requiring user opt-in for non-default language content.

Content

No source excerpt is available for this finding.

Natural-Language Policy Violations

Low

• Category: Not specified by scanner
• Confidence: 90% confidence

Finding

The printed table header includes Chinese labels like '大小' and '人格' alongside English, which imposes a locale choice in user-facing output. The file does not indicate that the language is optional, configurable, or justified as a region-specific tool.

Content

No source excerpt is available for this finding.

Natural-Language Policy Violations

Low

• Category: Not specified by scanner
• Confidence: 89% confidence

Finding

User-visible status strings such as '❌ 缺失', '总计', and '有灵魂' enforce Chinese-language output for part of the interface. Under the language-policy rule, this is a natural-language locale decision that should be optional or explicitly documented.

Content

No source excerpt is available for this finding.

Static analysis

No suspicious patterns detected.