Repository navigation
fix(ai): harden AgentSpec and Skill ZIP parsing - #15803
Conversation
Assisted-by: Claude Code
Assisted-by: Claude Code
Assisted-by: Claude Code
|
Thanks for your this PR. 🙏 感谢您提交的PR。 🙏 |
Move bundled Skill and AgentSpec seed archive parsing into their respective ZipParser classes while preserving bootstrap package metadata and limits. Assisted-by: Claude Code
Assisted-by: Claude Code
Assisted-by: Claude Code
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
Map unreadable multi-AgentSpec ZIP archives to the existing upload validation error contract and cover the regression with a parser unit test. Assisted-by: Claude Code
nacos-community
left a comment
There was a problem hiding this comment.
Summary
This PR consolidates AgentSpec/Skill ZIP parsing into dedicated parsers and adds solid hardening (decompression-size and entry-count limits, NUL/drive-path rejection, duplicate normalized-path detection), backed by good test coverage. Overall direction looks right; one consistency gap between SkillZipParser and AgentSpecZipParser deserves attention before merge.
Findings
- [Warning] ai/src/main/java/com/alibaba/nacos/ai/utils/SkillZipParser.java:735 — entries are stored under the original (un-normalized) name while
AgentSpecZipParser.unzipToEntriesstores the normalized name; e.g../SKILL.mdpasses validation but then fails SKILL.md lookup downstream. - [Warning] ai/src/main/java/com/alibaba/nacos/ai/utils/SkillZipParser.java:719 —
isIgnoredZipMetadataEntryis evaluated on the raw entry name instead of the normalized one, so separator variants of macOS metadata entries can bypass the filter (AgentSpecZipParser does this correctly). - [Info] ai/src/main/java/com/alibaba/nacos/ai/utils/AgentSpecZipParser.java:648 — with a root-level plus nested manifests, the empty-prefix root spec collects all entries as resources, overlapping subdirectory specs' resources.
Suggestions
In SkillZipParser.unzipToEntries, align with AgentSpecZipParser: compute normalizedName first, then use it for the isIgnoredZipMetadataEntry check, the shouldStore condition, and new ZipEntryData(normalizedName, ...). For the mixed-layout case, consider skipping entries owned by another manifest's prefix or documenting that mixing root and nested manifests in one ZIP is unsupported.
Automated review by github-manager-bot
| } | ||
| } | ||
| if (out != null) { | ||
| result.add(new ZipEntryData(name, out.toByteArray())); |
There was a problem hiding this comment.
SkillZipParser.unzipToEntries stores ZipEntryData with the original (un-normalized) entry name, while AgentSpecZipParser.unzipToEntries (line 504) correctly stores with the normalized name. This means a ZIP entry named './SKILL.md' passes normalizeEntryName (becoming 'SKILL.md') and validatePathSafety, but is then stored as './SKILL.md'. Downstream, findSkillMdEntry/isSkillMdEntryName (line 831) checks SKILL_MD_FILE.equals(name) and name.endsWith('/' + SKILL_MD_FILE), neither of which matches './SKILL.md', causing a 'SKILL.md file not found' failure for a valid entry. Similarly, containsRootSkillMdEntry (line 824) would miss it. Fix: store the normalized name, i.e. change line 735 to result.add(new ZipEntryData(normalizedName, out.toByteArray())) and update the shouldStore check at line 718-719 to use normalizedName consistently, matching what AgentSpecZipParser already does.
| } | ||
| ByteArrayOutputStream out = new ByteArrayOutputStream(); | ||
| boolean shouldStore = !entry.isDirectory() | ||
| && StringUtils.isNotBlank(name) && !isIgnoredZipMetadataEntry(name); |
There was a problem hiding this comment.
isIgnoredZipMetadataEntry is called on the raw (un-normalized) entry name instead of the normalized name. A ZIP entry like '.__MACOSX/blob' (backslash path separator) normalizes to '__MACOSX/blob' and passes validatePathSafety, but isIgnoredZipMetadataEntry('._MACOSX/blob') does not match any of the slash-based __MACOSX patterns (no '/' before __MACOSX) and isMacOsMetadataFile treats the whole string (no '/' found) as the filename, which doesn't start with '.'. The entry leaks through as a skill resource. AgentSpecZipParser correctly calls isMacOsMetadataFile on the normalized name at line 488. Fix: call isIgnoredZipMetadataEntry(normalizedName) and use normalizedName in the shouldStore condition.
|
|
||
| private static List<ZipEntryData> filterEntriesByPrefix(List<ZipEntryData> entries, | ||
| String prefix) { | ||
| if (prefix.isEmpty()) { |
There was a problem hiding this comment.
When parseMultipleAgentSpecsFromZip encounters a root-level manifest.json alongside subdirectory manifests (e.g. 'manifest.json' and 'worker-a/manifest.json'), getManifestPrefix returns '' for the root manifest, and filterEntriesByPrefix with an empty prefix returns ALL entries. The root-level AgentSpec then gets every non-manifest entry as a resource, including entries that belong to subdirectory specs (e.g. 'worker-a/config/a.md'). This resource overlap is not a security issue but could produce confusing results for uploads that mix layouts. Consider skipping entries whose name starts with another manifest's prefix, or document that root + nested manifests in one ZIP is unsupported.
Please do not create a Pull Request without creating an issue first.
What is the purpose of the change
Harden AgentSpec and Skill ZIP processing against unbounded decompression, entry-count flooding, ambiguous paths, and unsafe archive layouts. All AgentSpec ZIP flows now go through
AgentSpecZipParser, and all Skill ZIP flows go throughSkillZipParser, including bundled bootstrap archives.Brief changelog
AgentSpecZipParserand scope resources to the selected manifest directory.ZipParser, preserving bootstrap source metadata, standalone package reconstruction, and larger bootstrap-safe limits.AgentSpecSeedArchiveReaderandSkillSeedArchiveReaderimplementations.Verifying this change
mvn -pl api -Dtest=SkillUtilsTest testmvn -pl ai -am -Dtest=SkillZipParserTest,SkillZipParserSeedArchiveTest,SkillZipParserLimitsConfigTest,SkillZipParserRuntimeExceptionTest,AgentSpecZipParserTest,AgentSpecZipParserSeedArchiveTest,AgentSpecZipParserLimitsConfigTest,AgentSpecZipParserSecurityTest,SkillDataBootstrapInitializerTest,AgentSpecDataBootstrapInitializerTest -Dsurefire.failIfNoSpecifiedTests=false test(125 passed, 2 skipped because bundled seed ZIPs are not present in the local test runtime)mvn -pl ai -am -Dtest=AgentSpecOperationServiceImplTest -Dsurefire.failIfNoSpecifiedTests=false testmvn -pl ai -DskipTests spotless:applymvn -pl ai -DskipTests spotless:checkmvn -pl ai -DskipTests -Dcheckstyle.consoleOutput=true checkstyle:checkFollow this checklist to help us incorporate your contribution quickly and easily:
[ISSUE #123] Fix UnknownException when host config not exist. Each commit in the pull request should have a meaningful subject line and body.mvn spotless:applyto format your code. Runmvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTeststo make sure basic checks pass. Runmvn clean installto make sure unit-test pass. Runmvn clean test-compile failsafe:integration-testto make sure integration-test pass.