{"record":{"id":"e96c1a2c740cc7a1","repo":"iflytek/astron-agent","slug":"model-url-illegal-failed","errorCode":"MODEL_URL_ILLEGAL_FAILED","errorMessage":"MODEL_URL_ILLEGAL_FAILED","messagePattern":"MODEL_URL_ILLEGAL_FAILED","errorType":"error_code","errorClass":"BusinessException","httpStatus":null,"severity":"error","filePath":"console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/util/ssrf/SsrfParamGuard.java","lineNumber":57,"sourceCode":"     * Validation steps:\n     * </p>\n     * <ul>\n     * <li>Check if the URL scheme (protocol) is allowed.</li>\n     * <li>Check if the host is blocked by the configured IP blacklist (supporting both hostnames and\n     * IPs).</li>\n     * </ul>\n     *\n     * @param url the URL string to validate\n     * @throws BusinessException if the URL does not pass validation\n     */\n    public void validateUrlParam(String url) {\n        try {\n            SsrfValidators.Normalized n = SsrfValidators.normalizeFlex(url);\n            URL u = n.effectiveUrl;\n\n            // 1) Protocol and port\n            if (!SsrfValidators.isAllowedScheme(u.getProtocol(), props.getAllowedSchemes())) {\n                throw new BusinessException(ResponseEnum.MODEL_URL_ILLEGAL_FAILED);\n            }\n            if (!SsrfValidators.isAllowedScheme(u.getProtocol(), props.getAllowedSchemes())) {\n                throw new BusinessException(\n                        ResponseEnum.RESPONSE_FAILED,\n                        \"Only allowed schemes: \" + props.getAllowedSchemes());\n            }\n\n            // 2) IP blacklist (compatible with hostnames and IPs)\n            List<String> ipBlacklist = props.getIpBlaklist();\n            if (SsrfValidators.isHostDeniedByIpPolicy(\n                    u.getHost(), ipBlacklist, props.getIpWhitelist(), Dns.SYSTEM)) {\n                throw new BusinessException(ResponseEnum.MODEL_URL_CHECK_FAILED);\n            }\n\n        } catch (BusinessException e) {\n            throw e;\n        } catch (Exception e) {\n            log.error(\"[SSRF] URL validation failed\", e);","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/util/ssrf/SsrfParamGuard.java#L39-L75","documentation":"validateUrlParam rejects a model API URL whose protocol is not in the configured allowlist (props.getAllowedSchemes(), typically http/https). It throws MODEL_URL_ILLEGAL_FAILED as a BusinessException before any network request is made, as part of SSRF protection.","triggerScenarios":"buildModelApiUrlNew or validateSsrfForNodes is called with a model base URL whose scheme is not in props.getAllowedSchemes(), e.g. 'ftp://host/model' or 'file:///etc/passwd'. Note the identical guard is duplicated: the first throw wins, so this specific code fires before the RESPONSE_FAILED variant.","commonSituations":"Misconfigured model endpoint in the console (missing 'https://' prefix, or a custom scheme), YAML/env config where allowed-schemes omits a needed scheme, or a URL that after normalizeFlex resolves to a different scheme.","solutions":["Check the model URL passed to buildModelApiUrlNew/validateSsrfForNodes starts with an allowed scheme (usually https:// or http://).","Add the required scheme to props.getAllowedSchemes() in the SSRF guard configuration if the scheme is legitimately needed.","Inspect SsrfValidators.normalizeFlex output to see the effectiveUrl actually being validated (redirect-style normalization can change the scheme)."],"exampleFix":"// before\nString url = \"ftp://models.example.com/api\";\n// after\nString url = \"https://models.example.com/api\";","handlingStrategy":"validation","validationCode":"final String url = modelEndpoint;\njava.net.URI uri = java.net.URI.create(url);\nif (!\"https\".equals(uri.getScheme()) && !\"http\".equals(uri.getScheme())) {\n    throw new IllegalArgumentException(\"Model URL must be http(s): \" + url);\n}","typeGuard":null,"tryCatchPattern":"try {\n    ssrfParamGuard.validateUrlParam(url);\n} catch (BusinessException e) {\n    if (ResponseEnum.MODEL_URL_ILLEGAL_FAILED.equals(e.getCode())) {\n        log.warn(\"Rejected model URL scheme: {}\", sanitize(url));\n    }\n    throw e;\n}","preventionTips":["Always configure model endpoints with explicit https:// scheme.","Keep allowed-schemes config minimal (http/https only).","Unit-test buildModelApiUrlNew with each configured scheme."],"tags":["security","ssrf","url-validation","config"],"backgroundTag":"invalid-url","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}