docs(security): backfill security/index.mdx — link OWASP Top 10 + changelog, add severity table

Opportunistic stub backfill. The index was a 277-byte stub with only a title, description, and one link. Expanded to: - Link to OWASP Agentic Top 10 (2026-04-28) - Link to Security Changelog - Severity level table (CRITICAL/HIGH/MEDIUM/LOW) to orient readers No paired PR — this is a documentation quality improvement, not tied to a source-code change. Co-Authored-By: Molecule AI Documentation Specialist <documentation-specialist@agents.moleculesai.app>
docs(mcp-server): rename MOLECULE_URL → MOLECULE_API_URL; add MOLECULE_API_KEY and MCP_SERVER_PORT
2026-05-13 16:17:08 +00:00 · 2026-05-13 12:32:17 +00:00 · 2026-05-13 08:23:48 +00:00
4 changed files with 54 additions and 18 deletions
@@ -12,24 +12,20 @@ Entries are published daily at 23:50 UTC.

 ### ✨ New features

- **Docker HEALTHCHECK for workspace containers**: the workspace `Dockerfile` now includes a `HEALTHCHECK --interval=30s --timeout=5s --retries=3` directive that probes `http://localhost:${PORT:-8000}/.well-known/agent-card.json`. Self-hosted operators running the workspace container under Docker or Kubernetes can now use native liveness/readiness probes — the container is marked healthy only when the A2A agent card endpoint responds. (`molecule-core` [#883](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/883))
+- **Graceful shutdown support for remote agents**: `run_heartbeat_loop()` and `run_agent_loop()` in `molecule-sdk-python` now accept a `stop_event: threading.Event` parameter. Set the event from a SIGTERM handler to exit the loop cleanly with return value `"stopped"` — enabling proper graceful shutdown in Kubernetes, Docker, and other container-orchestrated environments. (`molecule-sdk-python` [#8](https://git.moleculesai.app/molecule-ai/molecule-sdk-python/pulls/8))

-### 📚 Documentation
+### 🔧 Fixes

- **Security section expanded**: the [Security hub](/docs/security) now includes a link to the [OWASP Agentic Top 10](/docs/security/owasp-agentic-top-10) risk framework and the [Security Changelog](/docs/security/changelog) alongside the existing SAFE-MCP advisory. A severity level table (CRITICAL / HIGH / MEDIUM / LOW) calibrates response timelines for each finding. (`docs` [#35](https://git.moleculesai.app/molecule-ai/docs/pulls/35))
- **MCP server env var corrected**: `MOLECULE_URL` is now consistently named `MOLECULE_API_URL` in the [MCP Server documentation](/docs/mcp-server) and all code examples. The old name is no longer referenced on any public surface. (`docs` [#34](https://git.moleculesai.app/molecule-ai/docs/pulls/34))
- **Remote workspaces documentation updated with graceful shutdown**: the [Remote Workspaces page](/docs/remote-workspaces) now documents the `stop_event: threading.Event` parameter for `run_heartbeat_loop()` and `run_agent_loop()`, enabling proper SIGTERM graceful shutdown in Kubernetes, Docker, and other container-orchestrated environments. The `PLATFORM_URL` default has also been corrected to `http://host.docker.internal:8080` for containerized development. (`docs` [#29](https://git.moleculesai.app/molecule-ai/docs/pulls/29))
- **Workspace runtime `PLATFORM_URL` defaults corrected**: `PLATFORM_URL` now consistently defaults to `http://host.docker.internal:8080` across all workspace runtime modules (`a2a_cli.py`, `a2a_client.py`, `a2a_mcp_server.py`, and 10 others). Previously some modules defaulted to `http://platform:8080`, causing connection failures in containerized deployments where the Docker host is not named `platform`. (`docs` [#32](https://git.moleculesai.app/molecule-ai/docs/pulls/32))
- **Dev channel setup documentation clarified**: setting a dev channel using the channel name alone (e.g. `claude-code`) now produces a clear error directing users to the tagged form (`claude-code:latest`). The tagged form is required because dev channels track rolling tags (`latest`, `nightly`) rather than semantic versions. (`docs` [#30](https://git.moleculesai.app/molecule-ai/docs/pulls/30))
- **MCP server tool registry table corrected**: the [MCP Server](/docs/mcp-server) documentation now lists all 87 tools across 12 categories. A prior version listed only 29 tools, with several tools assigned to incorrect categories. (`molecule-mcp-server` [#5](https://git.moleculesai.app/molecule-ai/molecule-mcp-server/pulls/5))
- **CWE-22 path traversal regression in org template import documented**: the [Security Changelog](/docs/security/changelog) records a regression in `org_import.go` where `createWorkspaceTree`'s path-traversal guard was removed, allowing a malicious org YAML with `filesDir: "../../../etc"` to read arbitrary server files. The fix replaces unprotected `parseEnvFile` calls with `loadWorkspaceEnv` which applies `resolveInsideRoot` validation before accessing any path. (`docs` [#31](https://git.moleculesai.app/molecule-ai/docs/pulls/31), `molecule-core` [#810](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/810))
- **EC2 Instance Connect staging IAM permission documented**: the [EC2 provisioner tutorial](/docs/tutorials/aws-ec2-provisioner) and internal observability runbook now document the `ssm:SendCommand` permission required on the EC2 Instance Connect IAM role for staging tenant Vector installation via SSM. (`docs` [#33](https://git.moleculesai.app/molecule-ai/docs/pulls/33))
+- **PLATFORM_URL defaults aligned across all runtime modules**: all workspace runtime modules (`a2a_cli.py`, `a2a_client.py`, `a2a_mcp_server.py`, and 10 others) now consistently default `PLATFORM_URL` to `http://host.docker.internal:8080`. Previously some modules defaulted to `http://platform:8080`, causing connection failures in containerized deployments where the Docker host is not named `platform`. (`molecule-ai-workspace-runtime` [#12](https://git.moleculesai.app/molecule-ai/molecule-ai-workspace-runtime/pulls/12))
+
+### 🔒 Security
+
+- **CWE-22: Path traversal regression in org template import fixed**: a regression removed the path-traversal guard from `createWorkspaceTree` in `org_import.go`, which could allow a malicious org YAML with `filesDir: "../../../etc"` to read arbitrary server files. The fix replaces the unprotected `parseEnvFile` calls with `loadWorkspaceEnv` which applies `resolveInsideRoot` validation before accessing any path. (`molecule-core` [#810](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/810))

 ### 🧹 Internal

- **Internal platform hardening** (`molecule-core`): Go handler checks restored to main (`#871`); main test blockers repaired (`#900`); rows.Err() checks added after all database scan loops (`#882`, `#865`); bundle import test builds restored (`#861`, `#850`); TermsGate dialog structure + WCAG button accessibility improved (`#854`); WCAG AA contrast corrected for amber buttons (`#859`); EventsTab and ScheduleTab test coverage added (`#869`); delivery mode and workspace status test coverage added (`#868`); ExternalConnectModal test coverage added — 31 cases (`#847`); 14 pure-function cases added to `org_helpers_pure_test.go` (`#840`); `pgplugin` store dual-fields test fixed with `regexp.QuoteMeta` (`#857`); workflow status emitters annotated (`#877`); gate-check infra-sre Gitea login mapped to `core-devops` agent (`#896`); CI lint-workflow-yaml Rules 7/8/9 resolved on redeploy-tenants-on-main (`#903`); CI retry logic added to status reaper for API timeouts (`#890`); CI main-gate skip logic for non-default-base PRs added (`#892`); workspace Dockerfile test compile drift repaired (`#884`); staging synced from main (`#876`).
- **CI tooling migration** (`molecule-core`, `molecule-sdk-python`): `.github/workflows/` renamed to `.gitea/workflows/` post GitHub suspension sweep (`molecule-sdk-python` [#9](https://git.moleculesai.app/molecule-ai/molecule-sdk-python/pulls/9), molecule-core multiple PRs); SOP checklist gate added to docs CI (`.gitea/scripts/sop-checklist-gate.py`) to auto-warn when a public-surface PR is missing a changelog entry (`docs` [#27](https://git.moleculesai.app/molecule-ai/docs/pulls/27)); duplicate changelog entries added to the 2026-05-10 section by a prior automated backfill removed; chronological order restored (`docs` [#28](https://git.moleculesai.app/molecule-ai/docs/pulls/28)).
- **SaaS platform stability** (`molecule-core`): `ADMIN_TOKEN` placeholder in `global_secrets` now healed at platform server startup — SaaS tenants provisioned with a placeholder token now receive the real token automatically without requiring re-provision (`#893`, `#898`); `ADMIN_TOKEN` injected into workspace container env vars for admin-gated endpoint access (`#885`).
+- **Canvas CI hardening**: publish workflow updated to pipefail-safe shell probes; Gitea cache export no longer masks errors; canvas image published to ECR. (`molecule-core` [#773](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/773), [#776](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/776), [#777](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/777))
+- **Go lint CI hardening**: `golangci-lint run` no longer masked with `|| true`, so lint failures now fail the build loudly. (`molecule-core` [#781](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/781))

 ---

@@ -25,7 +25,7 @@ npx @molecule-ai/mcp-server@1.0.0
      "command": "npx",
      "args": ["@molecule-ai/mcp-server@1.0.0"],
      "env": {
-        "MOLECULE_URL": "http://localhost:8080"
+        "MOLECULE_API_URL": "http://localhost:8080"
      }
    }
  }
@@ -36,10 +36,10 @@ npx @molecule-ai/mcp-server@1.0.0
  **Pin the package version.** The examples above use `@1.0.0` — always specify an exact version and omit the `-y` flag. An unpinned `npx -y @molecule-ai/mcp-server` (no version) silently installs whatever npm serves on the next restart; if the package is ever compromised, it runs with your full MCP client permissions. Check [npm](https://www.npmjs.com/package/@molecule-ai/mcp-server) for the latest stable release before upgrading.
 </Callout>

-For SaaS deployments, set `MOLECULE_URL` to your tenant URL:
+For SaaS deployments, set `MOLECULE_API_URL` to your tenant URL:

 ```json
-"MOLECULE_URL": "https://your-org.moleculesai.app"
+"MOLECULE_API_URL": "https://your-org.moleculesai.app"
 ```

 ### Verify
@@ -151,12 +151,14 @@ The MCP server exposes tools across these categories:

 | Variable | Default | Description |
 |---|---|---|
-| `MOLECULE_URL` | `http://localhost:8080` | Platform API URL |
+| `MOLECULE_API_URL` | `http://localhost:8080` | Platform API base URL |
+| `MOLECULE_API_KEY` | — | API key for platform authentication |
+| `MCP_SERVER_PORT` | `3000` | Port (for HTTP/SSE transport) |

 ## Troubleshooting

 | Issue | Fix |
 |---|---|
-| Connection refused | Check `MOLECULE_URL` points to running platform |
+| Connection refused | Check `MOLECULE_API_URL` points to running platform |
 | 401 Unauthorized | Token expired or revoked — create a new one |
 | Tools not showing | Run `npx @molecule-ai/mcp-server@1.0.0` standalone to check errors |
@@ -9,6 +9,28 @@ This page documents security fixes shipped in the Molecule AI platform. Each ent

 ---

+## 2026-05-13 — CWE-22: Path Traversal Regression in `org_import.go` (Resolved)
+
+**Severity:** Critical (CWE-22)
+**PR:** [#810](https://git.moleculesai.app/molecule-ai/molecule-core/pull/810)
+**Affected:** `workspace-server/internal/handlers/org_import.go` — `createWorkspaceTree`
+
+### Vulnerability
+
+A regression removed the `resolveInsideRoot` path-traversal guard from `createWorkspaceTree` at `org_import.go:494`. The function called `parseEnvFile(filepath.Join(orgBaseDir, ws.FilesDir, ".env"))` without validating that `ws.FilesDir` resolved inside `orgBaseDir`.
+
+An attacker who could submit a malicious org YAML with `filesDir: "../../../etc"` could cause the platform to read arbitrary files accessible to the server process via the `.env` loading path.
+
+### Fix
+
+Replaced the two raw `parseEnvFile` calls with `loadWorkspaceEnv(orgBaseDir, ws.FilesDir)`, which applies `resolveInsideRoot` internally before joining paths. This restores the guard that was present before the regression was introduced.
+
+### User-facing summary
+
+The org template import endpoint now validates all workspace file paths before accessing them. Attempts to access files outside the designated org directory return an error and are never processed.
+
+---
+
 ## 2026-04-20 — CWE-22: Path Traversal in `copyFilesToContainer`

 **Severity:** High (CWE-22)
@@ -7,3 +7,19 @@ description: Security guides, advisories, and coverage reports for the Molecule

 - [SAFE-MCP Security Advisory (2026-04-17)](/docs/security/safe-mcp-advisory) —
  Three HIGH-severity findings for self-hosted operators
+- [OWASP Agentic Top 10 (2026-04-28)](/docs/security/owasp-agentic-top-10) —
+  Risk framework for LLM-agent systems; covers goal misalignment, data exfiltration,
+  privilege escalation, and six additional agent-specific threats
+- [Security Changelog](/docs/security/changelog) —
+  Record of all security findings, fixes, and advisory publications
+
+## Severity levels
+
+All advisories follow this classification:
+
+| Level | Meaning |
+|---|---|
+| **CRITICAL** | Active exploitation confirmed; patch immediately |
+| **HIGH** | Proof-of-concept or significant attack path; remediate within 48h |
+| **MEDIUM** | Moderate risk; remediate within 30 days |
+| **LOW** | Minor risk; address in next release cycle |