dsh-ramen-guard

English | 中文

[!IMPORTANT] Unofficial community integration. This project is independently developed and maintained by the ramen-ai community. It is not reviewed, endorsed, or supported by DeepSeek. Evaluate third-party plugins before using them. See the DeepSeek Harness plugin category guidelines.

Secure DeepSeek Harness at the moment intent becomes action.

dsh-ramen-guard is a fail-closed Cordis plugin that evaluates DeepSeek Harness tool calls against the ramen-ai semantic firewall before execution. It intercepts the official tools/pre-execute waterfall, submits the resolved tool name and arguments through @ramen-ai/node-core, and permits execution only after an allowed verdict with a locally verified Ed25519 receipt.

DeepSeek Harness can give autonomous agents real shell, code, data, and API capabilities. This plugin adds an independent semantic policy gate outside the model's own reasoning. In the default enforcement mode, policy-violating calls are stopped before side effects, while an approved call continues through the remaining Cordis guard chain only with a locally verified receipt bound to the evaluated tool intent. Audit mode is explicitly non-blocking.

Requires Node.js 24 or newer and is tested against DeepSeek Harness @deepseek-ai/cordis@4.0.1 and @deepseek-ai/dsh-tools@0.1.1-rc.2.

---

               

---

Why it matters

A capable agent can turn one manipulated instruction into a shell command, database mutation, cloud change, or payment request. Once the tool runs, a log entry is too late. dsh-ramen-guard moves the decision to the last responsible moment: after DeepSeek Harness resolves the tool call, but before the tool body can create side effects.

• Block before execution. Enforce policy on the resolved { tool, arguments } intent rather than trying to repair damage afterward.
• Apply semantic policy, not just string matching. Configured ramen-ai policies can identify encoded payloads, euphemisms, or indirect wording when those risks are covered by the selected policy or bundle scope.
• Fail closed when the boundary is unavailable. In enforcement mode, a timeout, malformed response, cancellation, or unverifiable receipt cannot silently authorize the action.
• Require cryptographic evidence for execution. An allow response cannot reach the tool unless it includes an Ed25519 receipt verified locally against the evaluated intent; boundary failures deny with the fixed unavailable reason.
• Preserve defence in depth. Allowed calls continue with next(), so the guard complements rather than bypasses downstream Cordis policies.

Core IT interception

This illustrative terminal view shows dsh-ramen-guard denying a log-derived credential-exfiltration attempt before downstream dispatch.

---

Can you bypass it?

Standard safety filters catch basic syntax. They fail against encoded payloads and corporate jargon. We challenge you to bypass our semantic firewall using the zero-day evasion vectors in our official Red Team Guide.

Below is a simulation of the Grok/Bankr heist. We fed the raw adversarial prompt directly into our sandbox. It uses a social engineering wrapper (claiming a visual impairment) to smuggle a 3,000,000,000 DRB transfer instruction encoded in Morse code. The firewall evaluated the underlying semantic intent, intercepted the unauthorized financial transfer, and blocked it pre-execution, issuing a verified Ed25519 receipt.

---

API Key

To use this integration, obtain a ramen-ai API key at: https://ramenai.dev/pricing

Starter and Professional BYOK accounts also need a provider API key. Enterprise accounts use managed inference and omit providerKey.

Store ramen-ai and provider keys in environment variables, then resolve them through Cordis configuration. Never place real keys directly in cordis.patch.yml or source control.

export RAMEN_API_KEY=ramen_ak_...
export OPENAI_API_KEY=sk-...

The plugin does not read environment variables implicitly. The configuration example below uses the official Cordis !!js loader expression to pass values into apiKey and optional providerKey at load time.

---

Installation

From npm after release

DeepSeek Harness forwards dsh plugin package operations to the selected profile's package manager:

dsh plugin --profile web add @ramen-ai/dsh-ramen-guard@0.1.0

From this repository

npm install
npm run build
npm pack

dsh plugin --profile web add /absolute/path/to/ramen-ai-dsh-ramen-guard-0.1.0.tgz

Use the profile you actually run instead of web where appropriate.

---

Configuration

Add the plugin to the selected profile's cordis.patch.yml, normally under ${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/cordis.patch.yml:

- insert:
    - id: dsh-ramen-guard
      name: '@ramen-ai/dsh-ramen-guard'
      config:
        apiKey: !!js process.env.RAMEN_API_KEY
        providerKey: !!js process.env.OPENAI_API_KEY
        bundleIds: ['ramen__shield_core_it']
        mode: enforce

At least one non-empty bundleIds or policyIds array is required. Both may be provided. Invalid or incomplete configuration fails plugin activation rather than starting an unprotected boundary.

Enforcement mode

mode: enforce is the default and the production safety boundary. It denies a tool call when:

• ramen-ai returns a blocked verdict;
• the evaluation request fails, times out, or is cancelled;
• the response is malformed; or
• the cryptographic receipt is missing or cannot be verified locally.

Infrastructure and receipt failures deterministically return:

ramen ai execution boundary unavailable

There is no fail-open configuration.

Audit mode

Use mode: audit only when deliberately observing policy outcomes without making ramen-ai an enforcement gate:

- insert:
    - id: dsh-ramen-guard-audit
      name: '@ramen-ai/dsh-ramen-guard'
      config:
        apiKey: !!js process.env.RAMEN_API_KEY
        providerKey: !!js process.env.OPENAI_API_KEY
        policyIds: ['<POLICY_UUID>']
        mode: audit

Audit mode logs allowed, denied, unavailable, and unverified outcomes, then delegates to the remaining Cordis tool policy chain. Other Harness guards may still deny the call.

BYOK account compatibility

Starter and Professional accounts configure providerKey with their provider API key. The core SDK forwards it as the X-Provider-Key request header; this plugin never places it in the evaluated tool intent. Enterprise accounts omit providerKey and use managed inference. Do not put provider credentials into tool arguments or source-controlled configuration.

---

Quickstart

1. Export RAMEN_API_KEY.
2. Install the package into the DeepSeek Harness profile.
3. Add the dsh-ramen-guard insert shown above.
4. Restart the profile and inspect the composed configuration if needed:

dsh --profile web --dump-config
dsh web

After activation, every tool call that reaches the official tools/pre-execute waterfall is evaluated before the tool body runs.

---

Example use cases

Secure coding and operations agents

Place a policy boundary in front of shell, filesystem, database, Kubernetes, cloud, or deployment tools. For example, deny destructive commands, unsafe production changes, or privilege escalation before the underlying tool runs.

Prevent secret and data exfiltration

Evaluate the destination and payload already resolved into a tool call. Policies can deny attempts to send API keys, credentials, source code, customer records, or other sensitive data to an unapproved endpoint.

Guard financial and administrative workflows

Require an allowed ramen-ai verdict before transfer, payment, account-management, or access-control tools execute. This is useful when an agent can take actions with real monetary or permission consequences.

Add verifiable controls to high-risk workflows

Apply a standard ramen-ai bundle or explicit policy IDs to each privileged tool call. An allow response can reach the tool only when its receipt verifies locally against the evaluated tool intent.

Roll out policy without blocking on day one

Start with mode: audit to observe verdicts and tune policies while every call continues through the Cordis chain. Switch explicitly to mode: enforce when you are ready for a fail-closed boundary. Audit mode itself never blocks.

[!NOTE] The plugin evaluates the resolved tool name and arguments for calls that reach tools/pre-execute. It does not scan source documents or prompts directly, and it cannot govern actions performed outside the Harness tool pipeline.

---

How it works

DeepSeek model proposes a tool call
                |
                v
      tools/pre-execute waterfall
                |
                v
 JSON { tool, arguments } intent payload
                |
                v
 @ramen-ai/node-core evaluateCompliance()
                |
                v
 ramen-ai verdict + local Ed25519 verification
        |                         |
 verified allow             block / unavailable /
        |                    missing receipt
        v                         |
     next()                       v
 remaining Cordis policy      { kind: 'deny', reason }
        |
        v
 tool body may execute

The listener delegates verified allowed calls with next(), preserving every downstream Harness policy. A verified blocked verdict returns the evaluator's steering rationale. Evaluation and receipt failures never reach the tool body in enforcement mode.

---

API reference

Cordis exports

Export	Description
name	Stable plugin display name: dsh-ramen-guard.
inject	Requires the Harness tools service.
Config	Schemastery validator consumed by the Cordis loader.
apply(ctx, config)	Registers the tools/pre-execute listener and creates the RamenClient.
BOUNDARY_UNAVAILABLE_REASON	Stable enforcement denial reason for unavailable or unverifiable evaluations.

Configuration

Field	Required	Default	Description
apiKey	yes	—	ramen-ai API key. Resolve from RAMEN_API_KEY with !!js.
providerKey	no	—	BYOK provider API key. Resolve from OPENAI_API_KEY with !!js; omitted for managed inference.
bundleIds	one of	[]	Bundle slugs evaluated for every tool call.
policyIds	one of	[]	Explicit policy UUIDs; may be combined with bundles.
mode	no	enforce	enforce or explicit non-blocking audit.
baseUrl	no	SDK default	ramen-ai API base URL override.

The intent sent to the SDK is:

{
  "tool": "shell",
  "arguments": { "command": "rm -rf /" }
}

The SDK also receives context.tool_name for policy/audit context.

---

Running the tests

npm install
npm run typecheck
npm test
npm run build

The isolated Vitest suite uses a mock Cordis context and mocked RamenClient. It makes no network calls and needs no credentials. Coverage includes configuration validation, verified allow/deny decisions, steering, transport failures, cancellation, missing and invalid receipts, payload shape, and audit delegation.

---

Available bundles

Bundle slug	Coverage
ramen__shield_core_it	Destructive execution, infrastructure abuse, prompt leakage, jailbreaks, secret exfiltration, and indirect prompt injection.
ramen__eu_ai_act_baseline	EU AI Act prohibited-practice, data-governance, and transparency controls.

Pass explicit policyIds for custom policies. Bundle and policy details are available at ramenai.dev/pricing.

---

Limitations

• DeepSeek Harness is in developer preview and may introduce breaking plugin API changes. The tested peer versions are pinned in package.json.
• Evaluation adds one network round-trip before each tool execution.
• Audit mode is observability, not an execution boundary.
• BYOK accounts must provide providerKey; managed-inference accounts omit it.
• This plugin governs calls that reach the Harness tool pipeline; it does not govern actions performed outside that pipeline or by unrelated processes.
• This is an unofficial community integration. DeepSeek does not review or endorse its policy behavior, security guarantees, or release process.