feat(authoring): enforce endpoint, stdio and env security policies

Server-side validation and runtime clients now share a fail-closed
AuthoringSecurityPolicy:

- OpenAI-compatible and http/sse MCP endpoints are resolved and
  checked against SSRF rules at save time and again at connect time:
  any-local, link-local (cloud metadata) and multicast addresses are
  always rejected; loopback, RFC1918, unique-local IPv6 and CGNAT are
  rejected unless the per-surface allow-private-endpoints flag is set;
  unresolvable hosts are rejected. HTTP redirects are never followed
  and response bodies are capped at 2 MiB on both surfaces.
- stdio MCP transport is disabled by default (mcp.stdio-enabled) and,
  in docker execution mode, its command is wrapped in a hardened
  container (no network, dropped capabilities, read-only root, tmpfs,
  pid/memory/cpu limits) that is torn down when the client closes;
  stdio lines are capped at 2 MiB with force-kill on overflow.
- envRefs may only name variables in mcp.env-allowlist (empty by
  default, so every reference is rejected until an operator opts in).
- local-script execution-mode now defaults to docker; running inline
  outside the local/dev/test profiles fails startup.

Also renumbers the authoring migration V60 -> V66 to clear the slot
taken by upstream organization migrations.

Signed-off-by: zjncs <18910855655@163.com>
This commit is contained in:
zjncs 2026-09-21 10:28:52 +08:00
parent 6967b36493
commit ef1fac4a37
12 changed files with 626 additions and 27 deletions

View file

@ -1,5 +1,7 @@
package com.iflytek.skillhub.config;
import java.util.ArrayList;
import java.util.List;
import org.springframework.boot.context.properties.ConfigurationProperties;
/**
@ -25,6 +27,8 @@ public class AuthoringProperties {
private final OpenAiCompatible openAiCompatible = new OpenAiCompatible();
private final Mcp mcp = new Mcp();
public String getWorkspaceRoot() {
return workspaceRoot;
}
@ -65,6 +69,10 @@ public class AuthoringProperties {
return openAiCompatible;
}
public Mcp getMcp() {
return mcp;
}
/** Local script execution runtime. */
public static class LocalScript {
private boolean enabled = true;
@ -162,6 +170,13 @@ public class AuthoringProperties {
private int timeoutMs = 120_000;
/** Max chat-completion rounds per prompt task (each round may execute MCP tool calls). */
private int maxToolRounds = 4;
/**
* SSRF guard escape hatch for enterprise deployments whose LLM endpoint
* lives on a private network (e.g. an internal vLLM). Loopback and
* RFC1918 destinations stay blocked by default; link-local (cloud
* metadata) is always blocked.
*/
private boolean allowPrivateEndpoints = false;
public boolean isEnabled() {
return enabled;
@ -210,5 +225,113 @@ public class AuthoringProperties {
public void setMaxToolRounds(int maxToolRounds) {
this.maxToolRounds = maxToolRounds;
}
public boolean isAllowPrivateEndpoints() {
return allowPrivateEndpoints;
}
public void setAllowPrivateEndpoints(boolean allowPrivateEndpoints) {
this.allowPrivateEndpoints = allowPrivateEndpoints;
}
}
/**
* Security knobs for user-declared MCP servers. Defaults are the safe
* production posture: private endpoints blocked, stdio transport off, no
* environment references allowed. Local development relaxes them via
* application-local.yml.
*/
public static class Mcp {
/**
* When false (default), http/sse MCP endpoints pointing at loopback,
* RFC1918, ULA, or CGNAT addresses are rejected. Link-local addresses
* (cloud metadata) are always rejected.
*/
private boolean allowPrivateEndpoints = false;
/** When false (default), stdio MCP servers cannot be declared or spawned. */
private boolean stdioEnabled = false;
/** Server environment variables a binding may reference via envRefs. */
private List<String> envAllowlist = new ArrayList<>();
private final Docker docker = new Docker();
public boolean isAllowPrivateEndpoints() {
return allowPrivateEndpoints;
}
public void setAllowPrivateEndpoints(boolean allowPrivateEndpoints) {
this.allowPrivateEndpoints = allowPrivateEndpoints;
}
public boolean isStdioEnabled() {
return stdioEnabled;
}
public void setStdioEnabled(boolean stdioEnabled) {
this.stdioEnabled = stdioEnabled;
}
public List<String> getEnvAllowlist() {
return envAllowlist;
}
public void setEnvAllowlist(List<String> envAllowlist) {
this.envAllowlist = envAllowlist;
}
public Docker getDocker() {
return docker;
}
/** Isolation profile for stdio MCP servers in docker execution mode. */
public static class Docker {
private String image = "alpine:3.20";
private String memory = "256m";
private String cpus = "1.0";
private int pidsLimit = 128;
private String tmpfsSize = "64m";
public String getImage() {
return image;
}
public void setImage(String image) {
this.image = image;
}
public String getMemory() {
return memory;
}
public void setMemory(String memory) {
this.memory = memory;
}
public String getCpus() {
return cpus;
}
public void setCpus(String cpus) {
this.cpus = cpus;
}
public int getPidsLimit() {
return pidsLimit;
}
public void setPidsLimit(int pidsLimit) {
this.pidsLimit = pidsLimit;
}
public String getTmpfsSize() {
return tmpfsSize;
}
public void setTmpfsSize(String tmpfsSize) {
this.tmpfsSize = tmpfsSize;
}
}
}
}

View file

@ -0,0 +1,51 @@
package com.iflytek.skillhub.config;
import java.util.Arrays;
import java.util.Set;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.core.env.Environment;
import org.springframework.stereotype.Component;
/**
* Fails application startup when user-authored code would run directly on the
* host outside a development profile: with {@code skillhub.authoring.local-script}
* enabled in {@code INLINE} execution mode, validation scripts and stdio MCP
* commands execute as server subprocesses. Production deployments must use the
* {@code DOCKER} execution mode (or disable local-script entirely).
*/
@Component
public class AuthoringStartupGuard implements ApplicationRunner {
/** Profiles in which host-side execution is a deliberate development choice. */
private static final Set<String> NON_PRODUCTION_PROFILES = Set.of("local", "dev", "test");
private final AuthoringProperties properties;
private final Environment environment;
public AuthoringStartupGuard(AuthoringProperties properties, Environment environment) {
this.properties = properties;
this.environment = environment;
}
@Override
public void run(ApplicationArguments args) {
if (!properties.getLocalScript().isEnabled()) {
return;
}
if (properties.getLocalScript().getExecutionMode()
!= AuthoringProperties.ScriptExecutionMode.INLINE) {
return;
}
boolean nonProduction = Arrays.stream(environment.getActiveProfiles())
.anyMatch(NON_PRODUCTION_PROFILES::contains);
if (nonProduction) {
return;
}
throw new IllegalStateException("""
skillhub.authoring.local-script.execution-mode=inline is not allowed in \
production: user-authored scripts and stdio MCP commands would run \
directly on the host. Set SKILLHUB_AUTHORING_LOCAL_SCRIPT_MODE=docker \
(locked-down containers) or disable local-script.""");
}
}

View file

@ -0,0 +1,115 @@
package com.iflytek.skillhub.config;
import com.iflytek.skillhub.domain.authoring.service.AuthoringSecurityPolicy;
import java.net.InetAddress;
import java.net.URI;
import java.net.UnknownHostException;
import org.springframework.stereotype.Component;
/**
* The production {@link AuthoringSecurityPolicy}, derived from
* {@code skillhub.authoring.*} configuration.
*
* <p>SSRF posture: the server only makes outbound requests to public
* addresses. Link-local addresses (which include the 169.254.169.254 cloud
* metadata service), multicast, and the unspecified address are always
* rejected. Loopback, RFC1918, unique-local IPv6, and CGNAT ranges are
* rejected unless the surface-specific {@code allow-private-endpoints} flag
* is set (used by local development to reach loopback fake servers).
*
* <p>Known limitation: the guard resolves the hostname at check time; the
* HttpClient re-resolves at connect time, which mitigates (but cannot fully
* eliminate) DNS-rebinding races. Binding the socket to the checked address
* is not implemented because it would break virtual-hosted MCP endpoints.
*/
@Component
public class ConfiguredAuthoringSecurityPolicy implements AuthoringSecurityPolicy {
private final AuthoringProperties properties;
public ConfiguredAuthoringSecurityPolicy(AuthoringProperties properties) {
this.properties = properties;
}
@Override
public String endpointRejection(String url, EndpointUse use) {
URI uri;
try {
uri = URI.create(url);
} catch (IllegalArgumentException exception) {
return "malformed URL: " + url;
}
String scheme = uri.getScheme();
if (!"http".equalsIgnoreCase(scheme) && !"https".equalsIgnoreCase(scheme)) {
return "only http(s) endpoints are allowed, got: " + scheme;
}
String host = uri.getHost();
if (host == null || host.isBlank()) {
return "URL has no host: " + url;
}
boolean allowPrivate = use == EndpointUse.MCP_SERVER
? properties.getMcp().isAllowPrivateEndpoints()
: properties.getOpenAiCompatible().isAllowPrivateEndpoints();
InetAddress[] addresses;
try {
addresses = InetAddress.getAllByName(host);
} catch (UnknownHostException exception) {
return "cannot resolve host '" + host + "'";
}
for (InetAddress address : addresses) {
String reason = classify(address, allowPrivate);
if (reason != null) {
return reason;
}
}
return null;
}
@Override
public boolean stdioTransportAllowed() {
return properties.getMcp().isStdioEnabled();
}
@Override
public boolean envRefAllowed(String name) {
return properties.getMcp().getEnvAllowlist().contains(name);
}
/** @return null when the address is allowed, otherwise the rejection reason. */
private static String classify(InetAddress address, boolean allowPrivate) {
if (address.isAnyLocalAddress()) {
return "unspecified address is not a valid endpoint: " + address.getHostAddress();
}
if (address.isLinkLocalAddress()) {
// 169.254.0.0/16 (incl. the cloud metadata service) and fe80::/10
return "link-local address (cloud metadata range) is always blocked: "
+ address.getHostAddress();
}
if (address.isMulticastAddress()) {
return "multicast address is not a valid endpoint: " + address.getHostAddress();
}
boolean privateRange = address.isLoopbackAddress()
|| address.isSiteLocalAddress()
|| isUniqueLocalIpv6(address)
|| isCarrierGradeNat(address);
if (privateRange && !allowPrivate) {
return "private/loopback address is blocked unless allow-private-endpoints"
+ " is enabled: " + address.getHostAddress();
}
return null;
}
/** fc00::/7 unique-local addresses are not covered by {@code isSiteLocalAddress}. */
private static boolean isUniqueLocalIpv6(InetAddress address) {
byte[] bytes = address.getAddress();
return bytes.length == 16 && (bytes[0] & 0xFE) == 0xFC;
}
/** 100.64.0.0/10 carrier-grade NAT, a common internal service range. */
private static boolean isCarrierGradeNat(InetAddress address) {
byte[] bytes = address.getAddress();
return bytes.length == 4 && (bytes[0] & 0xFF) == 100
&& (bytes[1] & 0xFF) >= 64 && (bytes[1] & 0xFF) <= 127;
}
}

View file

@ -9,6 +9,7 @@ import com.iflytek.skillhub.domain.authoring.runtime.RuntimeEventSink;
import com.iflytek.skillhub.domain.authoring.runtime.RuntimeExecutionContext;
import com.iflytek.skillhub.domain.authoring.runtime.SkillRuntimeAdapter;
import com.iflytek.skillhub.domain.authoring.runtime.TaskResult;
import com.iflytek.skillhub.domain.authoring.service.AuthoringSecurityPolicy;
import com.iflytek.skillhub.domain.authoring.spec.TaskType;
import com.iflytek.skillhub.domain.authoring.spec.ValidationTaskSpec;
import com.iflytek.skillhub.service.authoring.mcp.HttpMcpClient;
@ -16,6 +17,7 @@ import com.iflytek.skillhub.service.authoring.mcp.McpClient;
import com.iflytek.skillhub.service.authoring.mcp.McpClientFactory;
import com.iflytek.skillhub.service.authoring.mcp.McpTool;
import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
@ -55,15 +57,21 @@ public class OpenAiCompatibleRuntimeAdapter implements SkillRuntimeAdapter {
private final AuthoringProperties properties;
private final ObjectMapper objectMapper;
private final McpClientFactory mcpClientFactory;
private final AuthoringSecurityPolicy securityPolicy;
private final HttpClient httpClient;
public OpenAiCompatibleRuntimeAdapter(AuthoringProperties properties, ObjectMapper objectMapper,
McpClientFactory mcpClientFactory) {
McpClientFactory mcpClientFactory,
AuthoringSecurityPolicy securityPolicy) {
this.properties = properties;
this.objectMapper = objectMapper;
this.mcpClientFactory = mcpClientFactory;
this.securityPolicy = securityPolicy;
this.httpClient = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(15))
// never follow redirects: a public endpoint answering 302 towards
// a link-local target must not become an SSRF bypass
.followRedirects(HttpClient.Redirect.NEVER)
.build();
}
@ -96,6 +104,14 @@ public class OpenAiCompatibleRuntimeAdapter implements SkillRuntimeAdapter {
throw new IllegalStateException(
"openai-compatible runtime requires endpoint and model (binding config or server defaults)");
}
// requests carry the server-side API key, so the destination must pass
// the SSRF guard before any credential leaves the host
String endpointRejection = securityPolicy.endpointRejection(
endpoint, AuthoringSecurityPolicy.EndpointUse.LLM_API);
if (endpointRejection != null) {
throw new IllegalStateException(
"openai-compatible endpoint is not allowed: " + endpointRejection);
}
String url = endpoint.endsWith("/") ? endpoint + "chat/completions" : endpoint + "/chat/completions";
Duration requestTimeout = Duration.ofMillis(Math.max(task.timeoutMs(), 1_000));
@ -278,13 +294,14 @@ public class OpenAiCompatibleRuntimeAdapter implements SkillRuntimeAdapter {
if (config.getApiKey() != null && !config.getApiKey().isBlank()) {
requestBuilder.header("Authorization", "Bearer " + config.getApiKey());
}
HttpResponse<String> response =
httpClient.send(requestBuilder.build(), HttpResponse.BodyHandlers.ofString());
HttpResponse<InputStream> response =
httpClient.send(requestBuilder.build(), HttpResponse.BodyHandlers.ofInputStream());
String body = HttpMcpClient.readBodyCapped(response.body(), HttpMcpClient.MAX_RESPONSE_BYTES);
if (response.statusCode() < 200 || response.statusCode() >= 300) {
throw new IOException("chat completion failed with HTTP " + response.statusCode()
+ ": " + truncate(response.body(), 500));
+ ": " + truncate(body, 500));
}
return objectMapper.readTree(response.body()).path("choices").path(0).path("message");
return objectMapper.readTree(body).path("choices").path(0).path("message");
}
private void appendToolReply(ArrayNode messages, String toolCallId, String content) {

View file

@ -4,7 +4,9 @@ import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
@ -19,12 +21,15 @@ import java.util.Map;
* MCP client for the streamable-HTTP transport (also used for legacy SSE
* endpoints that accept plain JSON-RPC POSTs). Each request is one JSON-RPC
* POST; responses may arrive as a bare JSON object or as a text/event-stream
* body whose data lines carry the JSON-RPC message.
* body whose data lines carry the JSON-RPC message. Response bodies are
* size-capped so a hostile endpoint cannot exhaust server memory.
*/
public class HttpMcpClient implements McpClient {
public static final String PROTOCOL_VERSION = "2024-11-05";
public static final String CLIENT_NAME = "skillhub-authoring";
/** One HTTP response body may not exceed this many bytes. */
public static final int MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
private final String serverName;
private final String endpoint;
@ -118,22 +123,23 @@ public class HttpMcpClient implements McpClient {
builder.header("Mcp-Session-Id", sessionId);
}
HttpResponse<String> response;
HttpResponse<InputStream> response;
try {
response = httpClient.send(builder.build(), HttpResponse.BodyHandlers.ofString());
response = httpClient.send(builder.build(), HttpResponse.BodyHandlers.ofInputStream());
} catch (IOException exception) {
throw new IOException("MCP server '" + serverName + "' request failed ("
+ method + "): " + exception, exception);
}
String body = readBodyCapped(response.body(), MAX_RESPONSE_BYTES);
if (response.statusCode() < 200 || response.statusCode() >= 300) {
throw new IOException("MCP server '" + serverName + "' returned HTTP "
+ response.statusCode() + " for " + method);
+ response.statusCode() + " for " + method + ": " + truncate(body, 200));
}
String sessionHeader = response.headers().firstValue("Mcp-Session-Id").orElse(null);
if (sessionHeader != null) {
sessionId = sessionHeader;
}
JsonNode message = parseMessage(response.body(), request.path("id").asInt());
JsonNode message = parseMessage(body, request.path("id").asInt());
if (message.has("error")) {
throw new IOException("MCP server '" + serverName + "' error on " + method + ": "
+ message.path("error").path("message").asText());
@ -228,4 +234,31 @@ public class HttpMcpClient implements McpClient {
calls.add(call.deepCopy());
}
}
/**
* Reads a response body fully into a UTF-8 string, refusing bodies beyond
* {@code maxBytes}: a hostile endpoint must not be able to buffer an
* unbounded response in server memory.
*/
public static String readBodyCapped(InputStream body, int maxBytes) throws IOException {
try (body) {
ByteArrayOutputStream buffer = new ByteArrayOutputStream();
byte[] chunk = new byte[8192];
int read;
while ((read = body.read(chunk)) != -1) {
if (buffer.size() + read > maxBytes) {
throw new IOException("response body exceeds " + maxBytes + " bytes");
}
buffer.write(chunk, 0, read);
}
return buffer.toString(StandardCharsets.UTF_8);
}
}
private static String truncate(String value, int limit) {
if (value == null) {
return "";
}
return value.length() <= limit ? value : value.substring(0, limit) + "…";
}
}

View file

@ -1,12 +1,16 @@
package com.iflytek.skillhub.service.authoring.mcp;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.iflytek.skillhub.config.AuthoringProperties;
import com.iflytek.skillhub.domain.authoring.service.AuthoringSecurityPolicy;
import java.io.IOException;
import java.net.http.HttpClient;
import java.time.Duration;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.UUID;
import org.springframework.stereotype.Component;
/**
@ -14,17 +18,33 @@ import org.springframework.stereotype.Component;
* declarations. Transport "http"/"sse" yield an HTTP JSON-RPC client; "stdio"
* spawns the declared command with only the envRefs-named variables from the
* server process environment (the only way credentials reach an MCP server).
*
* <p>Every declaration is re-checked here against the
* {@link AuthoringSecurityPolicy} even though the binding validator already
* rejected unsafe saves: this is the connect-time enforcement point that also
* covers bindings persisted by older deployments. In docker execution mode,
* stdio servers run inside the same locked-down container profile as
* validation scripts — no network, resource caps, read-only rootfs — and the
* container is force-removed when the client closes.
*/
@Component
public class McpClientFactory {
private final ObjectMapper objectMapper;
private final AuthoringProperties properties;
private final AuthoringSecurityPolicy securityPolicy;
private final HttpClient httpClient;
public McpClientFactory(ObjectMapper objectMapper) {
public McpClientFactory(ObjectMapper objectMapper, AuthoringProperties properties,
AuthoringSecurityPolicy securityPolicy) {
this.objectMapper = objectMapper;
this.properties = properties;
this.securityPolicy = securityPolicy;
this.httpClient = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10))
// redirects must never be followed: a public URL answering 302
// towards a link-local target is the classic SSRF bypass
.followRedirects(HttpClient.Redirect.NEVER)
.build();
}
@ -33,30 +53,104 @@ public class McpClientFactory {
String name = String.valueOf(server.get("name"));
String transport = String.valueOf(server.get("transport"));
if ("http".equals(transport) || "sse".equals(transport)) {
return new HttpMcpClient(name, String.valueOf(server.get("endpoint")),
httpClient, objectMapper, Map.of());
String endpoint = String.valueOf(server.get("endpoint"));
String rejection = securityPolicy.endpointRejection(
endpoint, AuthoringSecurityPolicy.EndpointUse.MCP_SERVER);
if (rejection != null) {
throw new IOException("MCP server '" + name + "' endpoint rejected: " + rejection);
}
return new HttpMcpClient(name, endpoint, httpClient, objectMapper, Map.of());
}
if ("stdio".equals(transport)) {
return new StdioMcpClient(name, commandOf(server), environmentOf(server), objectMapper);
if (!securityPolicy.stdioTransportAllowed()) {
throw new IOException("MCP server '" + name
+ "': stdio transport is disabled (skillhub.authoring.mcp.stdio-enabled)");
}
List<String> command = commandOf(server);
Map<String, String> environment = environmentOf(server);
if (properties.getLocalScript().getExecutionMode()
== AuthoringProperties.ScriptExecutionMode.DOCKER) {
String container = containerName(name);
return new StdioMcpClient(name, dockerWrappedCommand(container, command, environment),
Map.of(), objectMapper, List.of("docker", "rm", "-f", container), true);
}
return new StdioMcpClient(name, command, environment, objectMapper);
}
throw new IllegalArgumentException(
"MCP server '" + name + "' has unsupported transport: " + transport);
}
/**
* The docker argv that isolates a stdio MCP server: throwaway container,
* no network, resource caps, read-only rootfs, all capabilities dropped.
* Environment variables travel as explicit {@code -e} flags so the docker
* CLI can keep its own environment (needed to reach the daemon).
*/
List<String> dockerWrappedCommand(String container, List<String> command,
Map<String, String> environment) {
AuthoringProperties.Mcp.Docker docker = properties.getMcp().getDocker();
List<String> wrapped = new ArrayList<>();
wrapped.add("docker");
wrapped.add("run");
wrapped.add("--rm");
wrapped.add("--name");
wrapped.add(container);
wrapped.add("--network");
wrapped.add("none");
wrapped.add("--memory");
wrapped.add(docker.getMemory());
wrapped.add("--cpus");
wrapped.add(docker.getCpus());
wrapped.add("--pids-limit");
wrapped.add(String.valueOf(docker.getPidsLimit()));
wrapped.add("--read-only");
wrapped.add("--tmpfs");
wrapped.add("/tmp:rw,size=" + docker.getTmpfsSize());
wrapped.add("--cap-drop");
wrapped.add("ALL");
wrapped.add("--security-opt");
wrapped.add("no-new-privileges");
wrapped.add("--log-driver");
wrapped.add("none");
for (Map.Entry<String, String> entry : environment.entrySet()) {
wrapped.add("-e");
wrapped.add(entry.getKey() + "=" + entry.getValue());
}
wrapped.add(docker.getImage());
wrapped.addAll(command);
return List.copyOf(wrapped);
}
/** Container names allow [a-zA-Z0-9][a-zA-Z0-9_.-]+ and must be unique per client. */
static String containerName(String serverName) {
String sanitized = serverName == null ? "unknown" : serverName.replaceAll("[^a-zA-Z0-9_.-]", "-");
if (sanitized.isEmpty() || !Character.isLetterOrDigit(sanitized.charAt(0))) {
sanitized = "m" + sanitized;
}
return "skillhub-mcp-" + sanitized + "-" + UUID.randomUUID().toString().substring(0, 8);
}
/** Splits the command on whitespace; no shell is involved. */
private static List<String> commandOf(Map<String, Object> server) {
String command = String.valueOf(server.get("command"));
return List.of(command.trim().split("\\s+"));
}
/** Only envRefs-named variables from the server environment are passed through. */
private static Map<String, String> environmentOf(Map<String, Object> server) {
/**
* Only envRefs-named variables from the server environment are passed
* through, and only when the security policy allowlists them.
*/
Map<String, String> environmentOf(Map<String, Object> server) {
Map<String, String> environment = new HashMap<>();
if (server.get("envRefs") instanceof List<?> refs) {
for (Object ref : refs) {
String value = System.getenv(String.valueOf(ref));
String name = String.valueOf(ref);
if (!securityPolicy.envRefAllowed(name)) {
continue;
}
String value = System.getenv(name);
if (value != null) {
environment.put(String.valueOf(ref), value);
environment.put(name, value);
}
}
}

View file

@ -19,24 +19,48 @@ import java.util.concurrent.TimeUnit;
* MCP client for the stdio transport: the declared command is spawned as a
* subprocess and JSON-RPC messages are exchanged as newline-delimited JSON on
* its stdin/stdout. Only environment variables named in {@code envRefs} are
* passed through; the process is destroyed on close.
* passed through; the process is destroyed on close. A single stdout line is
* capped so a hostile server cannot exhaust memory with an unterminated line.
*/
public class StdioMcpClient implements McpClient {
/** One JSON-RPC message may not exceed this many characters. */
private static final int MAX_LINE_CHARS = 2 * 1024 * 1024;
private static final long TEARDOWN_TIMEOUT_MS = 5_000;
private final String serverName;
private final Process process;
private final BufferedWriter stdin;
private final BufferedReader stdout;
private final ObjectMapper objectMapper;
private final List<String> teardownCommand;
private int nextId = 1;
public StdioMcpClient(String serverName, List<String> command, Map<String, String> environment,
ObjectMapper objectMapper) throws IOException {
this(serverName, command, environment, objectMapper, null, false);
}
/**
* @param teardownCommand best-effort cleanup executed after the process is
* destroyed (e.g. {@code docker rm -f <container>});
* may be null
* @param inheritEnvironment when true the parent environment is kept — only
* legitimate for docker-wrapped commands, where the
* docker CLI needs it to reach the daemon and the
* container only receives its explicit {@code -e} vars
*/
public StdioMcpClient(String serverName, List<String> command, Map<String, String> environment,
ObjectMapper objectMapper, List<String> teardownCommand,
boolean inheritEnvironment) throws IOException {
this.serverName = serverName;
this.objectMapper = objectMapper;
this.teardownCommand = teardownCommand;
ProcessBuilder processBuilder = new ProcessBuilder(command);
processBuilder.environment().clear();
processBuilder.environment().putAll(environment);
if (!inheritEnvironment) {
processBuilder.environment().clear();
processBuilder.environment().putAll(environment);
}
processBuilder.redirectErrorStream(false);
this.process = processBuilder.start();
this.stdin = new BufferedWriter(
@ -106,6 +130,26 @@ public class StdioMcpClient implements McpClient {
process.destroyForcibly();
Thread.currentThread().interrupt();
}
runTeardown();
}
/**
* Best-effort cleanup after the process is gone: a SIGKILLed
* {@code docker run} client can leave its container behind, so the
* docker-wrapped mode removes the container by name.
*/
private void runTeardown() {
if (teardownCommand == null) {
return;
}
try {
Process cleanup = new ProcessBuilder(teardownCommand).start();
if (!cleanup.waitFor(TEARDOWN_TIMEOUT_MS, TimeUnit.MILLISECONDS)) {
cleanup.destroyForcibly();
}
} catch (IOException | InterruptedException exception) {
// cleanup is best-effort; the container also exits via --rm
}
}
private JsonNode request(String method, ObjectNode params, Duration timeout) throws Exception {
@ -144,7 +188,7 @@ public class StdioMcpClient implements McpClient {
try {
long deadline = System.nanoTime() + timeout.toNanos();
while (System.nanoTime() < deadline) {
String line = stdout.readLine();
String line = readLineCapped();
if (line == null) {
throw new IOException("MCP server '" + serverName + "' (stdio) closed its output");
}
@ -167,4 +211,26 @@ public class StdioMcpClient implements McpClient {
watchdog.interrupt();
}
}
/**
* Reads one line like {@link BufferedReader#readLine()} but refuses lines
* beyond {@link #MAX_LINE_CHARS}: a hostile stdio server could otherwise
* buffer an unterminated line of unbounded length in memory.
*/
private String readLineCapped() throws IOException {
StringBuilder line = new StringBuilder();
int character;
while ((character = stdout.read()) != -1) {
if (character == '\n' || character == '\r') {
return line.toString();
}
line.append((char) character);
if (line.length() > MAX_LINE_CHARS) {
process.destroyForcibly();
throw new IOException("MCP server '" + serverName
+ "' (stdio) sent a line longer than " + MAX_LINE_CHARS + " chars");
}
}
return line.length() == 0 ? null : line.toString();
}
}

View file

@ -53,6 +53,20 @@ skillhub:
moderation:
machine-review: ${SKILLHUB_PROFILE_MACHINE_REVIEW_ENABLED:true}
human-review: ${SKILLHUB_PROFILE_HUMAN_REVIEW_ENABLED:true}
authoring:
local-script:
# local development runs scripts on the host; production defaults to docker
execution-mode: ${SKILLHUB_AUTHORING_LOCAL_SCRIPT_MODE:inline}
openai-compatible:
# local fake LLM endpoints live on loopback
allow-private-endpoints: ${SKILLHUB_AUTHORING_LLM_ALLOW_PRIVATE:true}
mcp:
# local fake MCP servers live on loopback; link-local stays blocked
allow-private-endpoints: ${SKILLHUB_AUTHORING_MCP_ALLOW_PRIVATE:true}
# stdio servers may be exercised in local development
stdio-enabled: ${SKILLHUB_AUTHORING_MCP_STDIO_ENABLED:true}
# empty by default: envRefs are rejected in dev unless explicitly opened
env-allowlist: ${SKILLHUB_AUTHORING_MCP_ENV_ALLOWLIST:}
logging:
level:

View file

@ -207,10 +207,11 @@ skillhub:
maintenance-interval-ms: ${SKILLHUB_AUTHORING_MAINTENANCE_INTERVAL_MS:30000}
local-script:
enabled: ${SKILLHUB_AUTHORING_LOCAL_SCRIPT_ENABLED:true}
# inline: subprocess on the server host (local dev only).
# docker: script runs in a locked-down container — no network, memory/cpu/pids
# caps, read-only rootfs, all capabilities dropped. Use for production.
execution-mode: ${SKILLHUB_AUTHORING_LOCAL_SCRIPT_MODE:inline}
# docker is the production default: scripts run in a locked-down container —
# no network, memory/cpu/pids caps, read-only rootfs, all capabilities dropped.
# inline runs subprocesses on the server host and is only allowed with a
# local/dev/test profile (the startup guard fails fast otherwise).
execution-mode: ${SKILLHUB_AUTHORING_LOCAL_SCRIPT_MODE:docker}
docker:
# must provide the interpreters your skills use (alpine ships sh only)
image: ${SKILLHUB_AUTHORING_DOCKER_IMAGE:alpine:3.20}
@ -227,6 +228,25 @@ skillhub:
timeout-ms: ${SKILLHUB_AUTHORING_LLM_TIMEOUT_MS:120000}
# rounds of chat-completion (with MCP tool execution between rounds) per prompt task
max-tool-rounds: ${SKILLHUB_AUTHORING_LLM_MAX_TOOL_ROUNDS:4}
# SSRF guard: set true only for private-network LLM endpoints (e.g. internal vLLM);
# loopback/RFC1918 destinations are rejected by default, link-local always
allow-private-endpoints: ${SKILLHUB_AUTHORING_LLM_ALLOW_PRIVATE:false}
mcp:
# SSRF guard for http/sse MCP endpoints: private/loopback addresses are
# rejected by default; link-local (cloud metadata) is always rejected
allow-private-endpoints: ${SKILLHUB_AUTHORING_MCP_ALLOW_PRIVATE:false}
# stdio MCP servers spawn server-side processes — off unless explicitly enabled
stdio-enabled: ${SKILLHUB_AUTHORING_MCP_STDIO_ENABLED:false}
# server environment variables a binding may reference via envRefs
# (comma-separated, e.g. MCP_ECHO_TOKEN,WEATHER_API_KEY)
env-allowlist: ${SKILLHUB_AUTHORING_MCP_ENV_ALLOWLIST:}
docker:
# isolation profile for stdio MCP servers in docker execution mode
image: ${SKILLHUB_AUTHORING_MCP_DOCKER_IMAGE:alpine:3.20}
memory: ${SKILLHUB_AUTHORING_MCP_DOCKER_MEMORY:256m}
cpus: ${SKILLHUB_AUTHORING_MCP_DOCKER_CPUS:1.0}
pids-limit: ${SKILLHUB_AUTHORING_MCP_DOCKER_PIDS_LIMIT:128}
tmpfs-size: ${SKILLHUB_AUTHORING_MCP_DOCKER_TMPFS_SIZE:64m}
profile:
moderation:
machine-review: ${SKILLHUB_PROFILE_MACHINE_REVIEW_ENABLED:true} # Enable machine review (e.g. sensitive word detection)

View file

@ -0,0 +1,33 @@
package com.iflytek.skillhub.domain.authoring.service;
/**
* Security boundary for user-supplied runtime bindings, implemented by the
* application layer from {@code skillhub.authoring.*} configuration. The domain
* validator consults it at save time so that dangerous bindings are rejected
* before they can ever run.
*
* <p>Implementations must be conservative: an endpoint, transport, or
* environment reference that cannot be checked must be rejected, not allowed.
*/
public interface AuthoringSecurityPolicy {
/** Where a user-supplied URL is about to be used, so flags can differ per surface. */
enum EndpointUse {
MCP_SERVER,
LLM_API
}
/**
* Decides whether the server may make an outbound HTTP(S) request to the
* given URL (SSRF guard).
*
* @return {@code null} when the URL is allowed, otherwise the rejection reason
*/
String endpointRejection(String url, EndpointUse use);
/** Whether MCP servers may use the stdio transport (server-side process spawn). */
boolean stdioTransportAllowed();
/** Whether a binding may reference the named server environment variable. */
boolean envRefAllowed(String name);
}

View file

@ -13,7 +13,9 @@ import org.springframework.stereotype.Service;
* The CONFIG validation layer: checks the runtime binding (agent type, adapter
* configuration, tool allowlist, MCP server declarations) plus the syntactic validity
* of validation task assertions. Rejects embedded plaintext credentials — bindings may
* only reference server-side credential names.
* only reference server-side credential names. Outbound endpoints, the stdio
* transport, and environment references are additionally gated by the
* {@link AuthoringSecurityPolicy} so unsafe bindings are rejected at save time.
*/
@Service
public class RuntimeBindingValidator {
@ -26,6 +28,12 @@ public class RuntimeBindingValidator {
private static final List<String> TRANSPORTS = List.of("http", "sse", "stdio");
private static final List<String> INTERPRETERS = List.of("sh", "bash", "python3", "node");
private final AuthoringSecurityPolicy securityPolicy;
public RuntimeBindingValidator(AuthoringSecurityPolicy securityPolicy) {
this.securityPolicy = securityPolicy;
}
/**
* @param agentType agent type identifier (may be invalid — reported as finding)
* @param adapterConfig adapter-specific configuration map
@ -101,6 +109,15 @@ public class RuntimeBindingValidator {
} else if (!isHttpUrl(endpoint.toString())) {
findings.add(FindingDraft.error(ValidationLayer.CONFIG, "LLM_ENDPOINT_INVALID",
"endpoint must be an http(s) URL: " + endpoint));
} else {
// these requests carry the server-side API key; the SSRF guard must
// approve the destination before any credential can leave the host
String rejection = securityPolicy.endpointRejection(
endpoint.toString(), AuthoringSecurityPolicy.EndpointUse.LLM_API);
if (rejection != null) {
findings.add(FindingDraft.error(ValidationLayer.CONFIG, "LLM_ENDPOINT_BLOCKED",
"openai-compatible endpoint is not allowed: " + rejection));
}
}
Object model = config.get("model");
if (model == null || model.toString().isBlank()) {
@ -136,8 +153,20 @@ public class RuntimeBindingValidator {
if (endpoint == null || !isHttpUrl(endpoint.toString())) {
findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_ENDPOINT_INVALID",
"MCP server " + name + " requires an http(s) endpoint"));
} else {
String rejection = securityPolicy.endpointRejection(
endpoint.toString(), AuthoringSecurityPolicy.EndpointUse.MCP_SERVER);
if (rejection != null) {
findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_ENDPOINT_BLOCKED",
"MCP server " + name + " endpoint is not allowed: " + rejection));
}
}
} else {
if (!securityPolicy.stdioTransportAllowed()) {
findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_STDIO_DISABLED",
"MCP server " + name + " uses the stdio transport, which is disabled"
+ " (skillhub.authoring.mcp.stdio-enabled=false); use http/sse instead"));
}
Object command = server.get("command");
if (command == null || command.toString().isBlank()) {
findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_COMMAND_MISSING",
@ -159,6 +188,10 @@ public class RuntimeBindingValidator {
if (ref == null || !ENV_REF_NAME.matcher(ref.toString()).matches()) {
findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_ENV_REF_INVALID",
"MCP server " + name + " has an invalid env reference: " + ref));
} else if (!securityPolicy.envRefAllowed(ref.toString())) {
findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_ENV_REF_NOT_ALLOWED",
"MCP server " + name + " may not reference environment variable "
+ ref + " (not in skillhub.authoring.mcp.env-allowlist)"));
}
}
}