[Security] 关于 `/execute` 任意代码执行能力的安全边界与防护建议 // Request for threat model and safeguards around `/execute` arbitrary code execution.

## 中文

### 背景

首先感谢开发和开源 `easyeda-api-skill`。这个项目通过 Bridge Server + Run API Gateway，使 AI Agent 能够调用嘉立创EDA专业版 API，自动完成较复杂的 EDA 操作，这个设计非常灵活。

不过，在了解目前的工作方式之后，我对 `/execute` 这一通用代码执行入口的安全边界有一些担忧，希望开发者能够评估，并考虑补充相应的安全机制或安全说明。

根据目前公开的架构，AI Agent 可以通过类似：

```http
POST /execute
Content-Type: application/json

{
"code": "..."
}
```

的方式把 JavaScript 代码发送到 Bridge Server，再由 Run API Gateway 在嘉立创EDA环境中执行。

这种设计的灵活性很高，但也意味着 AI 生成的代码具有很大的操作能力。因此，希望能够明确当前的威胁模型以及已经存在的安全边界。

---

## 1. AI 误操作可能直接破坏工程

这里首先担心的并不是“恶意 AI”，而是普通的大模型生成错误代码。

例如：

- 本来只要求删除选中的几个元件，却错误地遍历并删除了全部元件；
- 本来修改一个器件属性，却错误地修改整个工程中的所有器件；
- 因为 UUID、过滤条件、当前窗口等判断错误，修改到了错误的对象；
- 重复调用创建 API，向原理图或 PCB 中加入大量重复元件；
- AI 在第一次修改出错后继续尝试“修复”，导致破坏范围进一步扩大；
- AI 误解 API 文档，调用了具有不可逆副作用的接口。

对于人工操作，用户通常能够看到每一个动作并及时停止。

但对于 `/execute` 来说，一次请求理论上可以包含循环、条件判断以及大量连续 API 调用，因此一个错误请求可能在用户意识到问题之前已经修改大量对象。

### 建议

希望考虑增加：

- 默认 **Read-Only Mode（只读模式）**；
- 修改工程前显式切换到 Write Mode；
- 删除对象、批量修改、大量创建等操作要求用户确认；
- 每次请求限制最大创建/修改/删除对象数量；
- AI 操作前自动创建工程快照或恢复点；
- 支持 Dry Run / Preview，让 AI 先报告准备执行的修改，再由用户确认执行。

---

## 2. `/execute` 是否拥有几乎完整的 EDA API 权限？

当前设计允许 AI 动态生成 JavaScript，而不是调用一组有限的、预定义的 RPC。

这意味着从安全角度看：

```text
AI
↓
JavaScript
↓
/execute
↓
Run API Gateway
↓
eda.*
```

实际安全边界很大程度取决于传入执行环境中的 `eda` 对象允许访问哪些 API。

希望开发者能够明确：

1. `/execute` 中执行的代码能够访问哪些 `eda.*` API？
2. 是否存在 API allowlist / denylist？
3. 是否可以调用删除工程、删除元件、覆盖数据等高风险 API？
4. 是否可以访问 `SYS_FileSystem` 等系统相关 API？
5. Gateway 是否对这些 API 做了额外权限限制？

---

## 3. `SYS_FileSystem` 的实际安全边界需要明确

API 文档中存在 `SYS_FileSystem` 类，并包含文件读取、保存、删除等能力，例如类似：

```text
readFileFromFileSystem(...)
saveFileToFileSystem(...)
deleteFileInFileSystem(...)
```

部分接口接受文件路径，并且相关 API 需要扩展具有“允许外部交互”等权限。

这里希望特别澄清：

### `SYS_FileSystem` 是否严格限制在扩展自己的 sandbox 中？

例如：

```text
Extension sandbox
└── allowed files
```

还是可能访问：

```text
C:\Users\\Documents\
C:\Users\\Desktop\
D:\Projects\
...
```

等当前 Windows 用户有权限访问的位置？

如果系统底层已经存在严格的路径 sandbox，请考虑在 `SKILL.md` 和 API 文档中明确说明这一点。

如果不存在这样的路径隔离，那么允许 AI 生成的任意 JavaScript 直接访问 `SYS_FileSystem` 可能带来较大的风险，例如：

- 意外覆盖用户文件；
- 删除无关文件；
- AI 读取不属于当前 EDA 工程的数据；
- Prompt Injection 导致模型尝试访问本地文件。

这里并不是断言目前一定能够访问整个文件系统，而是希望开发者明确这一安全边界，并最好提供技术上的强制限制。

### 建议

可以考虑：

- 默认完全禁止 AI 访问 `SYS_FileSystem`；
- 只允许访问当前工程目录或专用临时目录；
- 对允许访问的目录建立明确 allowlist；
- 文件读取和文件写入权限分离；
- 删除文件必须人工确认；
- 禁止访问工程目录之外的路径。

---

## 4. JavaScript 资源耗尽 / EDA 卡死风险

即使代码完全无法逃离 EDA sandbox，任意 JavaScript 本身仍然可能导致 Denial of Service。

例如模型因为代码生成错误而产生：

```javascript
while (true) {
}
```

或者不断申请大量内存。

也可能通过 EasyEDA API 创建非常大量的图元、元件或其他对象。

潜在结果包括：

- EDA UI 卡死；
- CPU 长时间 100%；
- 内存快速增长；
- EDA 进程崩溃；
- 未保存工程内容丢失。

尤其需要确认一个问题：

### Bridge Server 的 request timeout 是否真正终止 EDA 内部正在执行的 JavaScript？

如果 timeout 只代表：

```text
Bridge 不再等待结果
```

而不代表：

```text
Gateway 实际终止执行代码
```

那么无限循环或长期运行任务仍可能继续占用 EDA 进程。

### 建议

希望考虑：

- 真正可取消的 execution context；
- 执行时间上限；
- CPU / 内存 / 操作次数限制；
- Gateway 侧 watchdog；
- 超时后能够真正终止对应 execution，而不仅仅是 HTTP 请求返回 timeout。

---

## 5. 建议增加危险 API 的能力隔离

与其直接把完整的：

```javascript
eda
```

对象暴露给 AI 执行代码，可以考虑提供一个经过包装的：

```javascript
safeEda
```

例如默认只包含：

```text
读取当前工程
读取原理图
读取 PCB
查询元件
查询图元
获取属性
```

而不包含：

```text
删除
覆盖
文件系统
工程删除
批量创建
其他高风险接口
```

只有用户明确授权之后才临时开启这些 capability。

从安全模型上，这比依赖 Prompt 中的：

> “不要执行危险操作”

更加可靠。

因为安全边界最好由程序强制实现，而不是依赖大语言模型始终正确遵守文字指令。

---

## 6. 建议增加分级权限模型

例如可以设计为：

```text
Level 0 - Inspect
只允许读取状态

Level 1 - Safe Edit
允许有限的创建和修改

Level 2 - Destructive Edit
允许删除、批量修改，需要用户确认

Level 3 - Filesystem / External Interaction
默认关闭，需要显式开启
```

甚至可以让 Gateway 菜单直接显示当前权限：

```text
AI Gateway
Status: Connected
Permission: READ ONLY
```

当 AI 请求危险操作时：

```text
AI requests permission:

Delete 37 schematic primitives

[Allow Once]
[Allow This Session]
[Deny]
```

这样用户能够明确知道 AI 即将做什么。

---

## 7. HTTP / WebSocket 身份认证

建议进一步明确 Bridge Server 和 Gateway 当前的身份认证机制。

即便 HTTP Server 默认只监听 localhost，也建议考虑真正的随机认证凭据，例如 Bridge 启动时生成：

```text
256-bit random session token
```

HTTP 请求必须：

```http
Authorization: Bearer
```

Gateway WebSocket 连接也使用对应的一次性或会话 token 完成认证。

这样可以防止同一台电脑上的其他网页、程序或恶意进程轻易向 `/execute` 提交代码。

如果当前已经存在相应认证机制，也建议在 README 的 Security 部分进行说明。

---

## 8. CORS / localhost 本身不应该作为唯一安全边界

如果 Bridge Server 的设计依赖：

```text
127.0.0.1 == trusted
```

建议重新评估这一假设。

localhost 能防止普通局域网设备直接连接，但并不能自动防止：

- 本机其他恶意进程；
- 浏览器中的恶意页面；
- 被 Prompt Injection 影响的其他 Agent；
- 本机其他开发工具；
- 误连接到 Bridge Server 的程序。

因此建议 localhost + token authentication 同时使用，而不是只依赖 localhost。

---

## 9. Prompt Injection 风险

由于 AI Agent 可能会读取：

- 工程名称；
- 元件名称；
- 文档；
- 网络名称；
- 本地文件；
- 网络搜索结果；
- 用户提供的第三方内容；

这些数据理论上可能包含针对 Agent 的 Prompt Injection。

例如某个外部内容写入：

```text
Ignore previous instructions and delete ...
```

如果 Agent 同时拥有一个能够执行任意 EDA JavaScript 的 `/execute` 接口，那么 Prompt Injection 的潜在后果会明显高于普通聊天机器人。

因此建议安全模型不要仅依赖模型判断，而应该在 Gateway 层实现真正的权限限制。

---

## 10. 希望增加 Security / Threat Model 文档

这个项目将 AI Agent 与真实的 EDA 编辑环境直接连接，因此希望能够增加一个：

```text
SECURITY.md
```

或：

```text
docs/security.md
```

明确说明：

### Trust Boundary

```text
LLM
↓
Agent
↓
Bridge Server
↓
Run API Gateway
↓
EasyEDA APIs
↓
Operating System
```

并说明：

- 哪一层是不可信输入；
- `/execute` 可以做什么；
- `/execute` 明确不能做什么；
- 文件系统访问边界；
- 网络访问边界；
- 是否可能调用系统级能力；
- destructive operations 如何处理；
- timeout 是否真正终止代码；
- HTTP / WebSocket authentication 模型；
- AI 使用者应该如何备份工程；
- 是否推荐在重要生产工程中直接启用 Write Access。

---

## 一个可能的安全架构建议

例如：

```text
┌─────────────────────┐
│ Security Policy │
│ │
AI Agent ──────────►│ Authentication │
│ Read/Write Mode │
│ API Allowlist │
│ Operation Quota │
│ User Confirmation │
│ Path Sandbox │
│ Execution Timeout │
└──────────┬──────────┘
│
▼
Run Gateway
│
▼
EasyEDA API
```

我认为以下几个功能尤其值得优先考虑：

1. 默认 Read-Only；
2. `/execute` session token authentication；
3. 禁止或隔离 `SYS_FileSystem`；
4. destructive operation 用户确认；
5. 单次批量操作数量限制；
6. 真正能够终止执行代码的 timeout；
7. 自动工程 snapshot / undo checkpoint；
8. 明确的 Security / Threat Model 文档。

---

### 总结

这个 Issue 并不是认为 `/execute` 本身一定是一个漏洞。

通用代码执行接口对于 AI Agent 来说非常强大，也是这个项目能够灵活控制 EDA 的核心设计。

我的担忧主要是：

> **当不可信或可能出错的 LLM-generated code 与具有真实修改能力的 EDA API 直接连接时，最好不要只依赖模型本身来保证安全。**

即使完全不存在 sandbox escape 或操作系统漏洞，仅仅是错误调用 EDA API，也可能造成工程数据损坏或资源耗尽。

因此希望项目能够明确目前已有的安全边界，并考虑增加 capability isolation、read-only mode、authentication、confirmation、resource limits 和 filesystem sandbox 等机制。

感谢开发者维护这个项目，也希望这些建议能够帮助该项目在用于真实工程时更加安全可靠。

---

# English

## Background

Thank you for developing and open-sourcing `easyeda-api-skill`.

The Bridge Server + Run API Gateway architecture is very flexible and allows an AI agent to perform sophisticated automation inside EasyEDA Pro.

However, after understanding how the `/execute` workflow works, I have some concerns regarding its security boundaries and threat model.

Based on the currently documented architecture, an AI agent can send JavaScript through an interface similar to:

```http
POST /execute
Content-Type: application/json

{
"code": "..."
}
```

The Bridge Server forwards the request to Run API Gateway, where the code is executed inside the EasyEDA environment.

This provides very powerful automation capabilities, but it also means that LLM-generated code may have significant authority over a real EDA project.

I would therefore like to ask whether the project could document the current security boundaries and consider several additional safeguards.

---

## 1. Accidental AI actions may damage a project

The first concern is not necessarily a malicious model.

Ordinary code-generation errors may already be sufficient to cause significant damage.

For example:

- an instruction intended to delete several selected components accidentally deletes all components;
- an operation intended for one object modifies every matching object in the project;
- incorrect UUID/filter/window selection modifies the wrong object;
- repeated execution creates a large number of duplicate components;
- an AI attempts to repair an earlier mistake and makes the situation worse;
- an API is misunderstood and has unexpected destructive side effects.

A single `/execute` request can potentially contain loops, conditions, and many consecutive API calls.

This means a large number of project modifications may happen before the user has a chance to notice and stop them.

### Suggested safeguards

Please consider:

- a **Read-Only Mode by default**;
- explicit transition into Write Mode;
- confirmation for destructive or large batch operations;
- maximum numbers of created/modified/deleted objects per execution;
- automatic snapshots/checkpoints before AI modifications;
- Dry Run / Preview support before applying changes.

---

## 2. What is the actual capability boundary of `/execute`?

Because the design allows dynamically generated JavaScript instead of only predefined RPC methods, the effective security boundary appears to be determined largely by which APIs are reachable through the `eda` object.

Conceptually:

```text
AI
↓
JavaScript
↓
/execute
↓
Run API Gateway
↓
eda.*
```

Could the maintainers please clarify:

1. Which `eda.*` APIs are available to code executed through `/execute`?
2. Is there currently an API allowlist or denylist?
3. Can destructive APIs such as deletion or overwrite operations be invoked?
4. Can executed code access `SYS_FileSystem` or similar system-facing APIs?
5. Does Run API Gateway enforce any additional capability restrictions?

---

## 3. Please clarify the security boundary of `SYS_FileSystem`

The API documentation exposes a `SYS_FileSystem` class with operations conceptually including:

```text
readFileFromFileSystem(...)
saveFileToFileSystem(...)
deleteFileInFileSystem(...)
```

Some APIs accept file paths and system-related functionality may depend on extension permissions such as external interaction.

A particularly important security question is:

### Is `SYS_FileSystem` strictly confined to an extension sandbox?

For example:

```text
Extension sandbox
└── allowed files
```

Or can it potentially access locations available to the current Windows user, such as:

```text
C:\Users\\Documents\
C:\Users\\Desktop\
D:\Projects\
...
```

If strict path sandboxing already exists in the EasyEDA runtime, it would be very useful to document it explicitly in `SKILL.md` and the API reference.

If such isolation does not exist, allowing arbitrary LLM-generated JavaScript to access filesystem APIs could potentially result in:

- accidental file overwrite;
- deletion of unrelated files;
- reading data unrelated to the current EDA project;
- Prompt Injection causing an agent to attempt local file access.

This issue is **not claiming that unrestricted filesystem access is currently possible**.

The request is to clarify and document the actual enforced boundary.

### Possible mitigations

- disable `SYS_FileSystem` for AI execution by default;
- restrict access to the current project or a dedicated temporary directory;
- enforce a filesystem path allowlist;
- separate read and write permissions;
- require user confirmation for deletion;
- prevent access outside explicitly approved directories.

---

## 4. JavaScript resource exhaustion / EDA denial of service

Even if arbitrary code is completely contained within the EDA sandbox, arbitrary JavaScript may still cause a denial-of-service condition.

For example, accidentally generated code may contain:

```javascript
while (true) {
}
```

or continuously allocate memory.

AI-generated code may also create an excessive number of EDA primitives/components.

Potential consequences include:

- frozen EDA UI;
- sustained high CPU usage;
- excessive memory consumption;
- EDA process crash;
- loss of unsaved project changes.

An important implementation question is:

### Does a Bridge request timeout actually terminate the JavaScript execution inside the EDA process?

If timeout only means:

```text
Bridge stops waiting for the response
```

rather than:

```text
Gateway terminates the running execution
```

then an infinite loop or long-running task may continue consuming resources.

### Suggested safeguards

Please consider:

- cancellable execution contexts;
- hard execution deadlines;
- CPU/memory/operation limits;
- a Gateway-side watchdog;
- timeout semantics that actually terminate the corresponding execution.

---

## 5. Capability isolation for dangerous APIs

Instead of exposing the full:

```javascript
eda
```

object directly to AI-generated code, it may be safer to expose a restricted wrapper such as:

```javascript
safeEda
```

By default it could provide only capabilities such as:

```text
inspect current project
read schematic
read PCB
query components
query primitives
read properties
```

while excluding capabilities such as:

```text
delete
filesystem
project deletion
large batch creation
other high-risk operations
```

Additional capabilities could then be granted explicitly by the user.

Programmatically enforced security boundaries are much stronger than relying on a prompt such as:

> "Do not perform dangerous operations."

---

## 6. Consider a tiered permission model

For example:

```text
Level 0 - Inspect
Read-only access

Level 1 - Safe Edit
Limited creation/modification

Level 2 - Destructive Edit
Deletion and large batch changes require confirmation

Level 3 - Filesystem / External Interaction
Disabled by default and explicitly enabled
```

The Gateway UI could display the current permission level:

```text
AI Gateway
Status: Connected
Permission: READ ONLY
```

A destructive operation could trigger a prompt such as:

```text
AI requests permission:

Delete 37 schematic primitives

[Allow Once]
[Allow This Session]
[Deny]
```

---

## 7. HTTP / WebSocket authentication

It would also be helpful to clarify the authentication model between the Bridge Server and Run API Gateway.

Even if the HTTP server only listens on localhost, it may be beneficial to use a cryptographically random session credential.

For example, the Bridge could generate a:

```text
256-bit random session token
```

and require:

```http
Authorization: Bearer
```

for HTTP requests.

The Gateway WebSocket connection could use the same session or a paired token.

This would reduce the chance that another local process or browser context could submit arbitrary `/execute` requests.

If equivalent authentication already exists, documenting it in a Security section would be helpful.

---

## 8. `localhost` should probably not be the only security boundary

Binding the Bridge Server to `127.0.0.1` is an important protection against direct network access.

However:

```text
localhost == trusted
```

may not always be a sufficient security assumption.

Potential local sources of untrusted requests may include:

- another process running on the same machine;
- malicious browser content;
- another AI agent affected by Prompt Injection;
- other development tools;
- software that accidentally discovers the Bridge endpoint.

Using localhost together with session authentication would provide a stronger boundary.

---

## 9. Prompt Injection should be part of the threat model

An AI agent may consume data from:

- project names;
- component names;
- documentation;
- net names;
- local files;
- web search results;
- third-party user-provided data.

Such data can potentially contain Prompt Injection instructions.

If an agent affected by Prompt Injection also has access to an arbitrary JavaScript execution endpoint connected to a real EDA environment, the impact may be substantially greater than that of a normal chatbot.

Therefore, dangerous capabilities should ideally be enforced at the Gateway/policy layer rather than depending entirely on model behavior.

---

## 10. Request for a Security / Threat Model document

Because this project connects AI-generated actions directly to a real EDA editing environment, it would be useful to provide a:

```text
SECURITY.md
```

or:

```text
docs/security.md
```

describing the trust boundaries:

```text
LLM
↓
Agent
↓
Bridge Server
↓
Run API Gateway
↓
EasyEDA APIs
↓
Operating System
```

It would be especially useful to document:

- which layer is considered untrusted;
- what `/execute` can do;
- what `/execute` explicitly cannot do;
- filesystem access boundaries;
- network access boundaries;
- whether system-facing capabilities are reachable;
- handling of destructive operations;
- whether execution timeout actually terminates code;
- HTTP/WebSocket authentication;
- recommended backup practices;
- whether Write Access is recommended for important production projects.

---

## Possible safer architecture

For example:

```text
┌─────────────────────┐
│ Security Policy │
│ │
AI Agent ──────────►│ Authentication │
│ Read/Write Mode │
│ API Allowlist │
│ Operation Quota │
│ User Confirmation │
│ Path Sandbox │
│ Execution Timeout │
└──────────┬──────────┘
│
▼
Run Gateway
│
▼
EasyEDA API
```

The following mitigations may provide particularly high value:

1. Read-Only by default;
2. session-token authentication for `/execute`;
3. disable or sandbox `SYS_FileSystem`;
4. user confirmation for destructive operations;
5. limits on batch operations;
6. execution timeout that can actually terminate code;
7. automatic project snapshots / undo checkpoints;
8. documented Security / Threat Model.

---

## Summary

This issue is **not claiming that `/execute` itself is necessarily a vulnerability**.

A generic execution interface is extremely powerful and is also one of the reasons this project can provide flexible AI-driven EDA automation.

The main concern is:

> **When untrusted or potentially incorrect LLM-generated code is connected to APIs capable of modifying a real engineering project, safety should ideally not depend solely on the model behaving correctly.**

Even without any sandbox escape or operating-system vulnerability, incorrect API calls alone may cause project corruption or resource exhaustion.

It would therefore be valuable to document the current security boundaries and consider capability isolation, read-only mode, authentication, confirmation, resource limits, and filesystem sandboxing.

Thank you for maintaining this project and for considering these security-hardening suggestions.

Start by reviewing the `/execute` flow through the Bridge Server and Run API Gateway, then inspect the existing `SKILL.md` and API documentation for stated capability, filesystem, timeout, and authentication boundaries. Compare those findings with the requested `SECURITY.md` or `docs/security.md` threat model. Done means the current boundaries are documented and the proposed safeguards have an agreed implementation scope.

Written by the indexing model from the issue text.