Skip to content

fix(ai): harden AgentSpec and Skill ZIP parsing - #15803

Merged
KomachiSion merged 7 commits into
alibaba:developfrom
saynoword:fix/agentspec-skill-zip-security
Sep 7, 2026
Merged

KomachiSion merged 7 commits into
alibaba:developfrom
saynoword:fix/agentspec-skill-zip-security

Conversation

@saynoword

@saynoword saynoword commented Sep 1, 2026 •

Copy link
Copy Markdown
Contributor

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 through SkillZipParser, including bundled bootstrap archives.

Brief changelog

  • Reject NUL bytes, Windows drive paths, and duplicate normalized ZIP entry paths.
  • Count directory and ignored metadata entries toward configurable entry and decompressed-size limits.
  • Parse single and multi-AgentSpec uploads directly through AgentSpecZipParser and scope resources to the selected manifest directory.
  • Move bundled AgentSpec and Skill archive parsing into the corresponding ZipParser, preserving bootstrap source metadata, standalone package reconstruction, and larger bootstrap-safe limits.
  • Remove the separate AgentSpecSeedArchiveReader and SkillSeedArchiveReader implementations.
  • Add regression tests for configurable limits, ignored metadata, duplicate paths, nested layouts, seed archives, bootstrap initialization, and upload behavior.

Verifying this change

  • mvn -pl api -Dtest=SkillUtilsTest test
  • mvn -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 test
  • mvn -pl ai -DskipTests spotless:apply
  • mvn -pl ai -DskipTests spotless:check
  • mvn -pl ai -DskipTests -Dcheckstyle.consoleOutput=true checkstyle:check

Follow this checklist to help us incorporate your contribution quickly and easily:

  • Make sure there is a Github issue filed for the change (usually before you start working on it). Trivial changes like typos do not require a Github issue. Your pull request should address just this issue, without pulling in other changes - one PR resolves one issue.
  • Format the pull request title like [ISSUE #123] Fix UnknownException when host config not exist. Each commit in the pull request should have a meaningful subject line and body.
  • Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
  • Write necessary unit-test to verify your logic correction, more mock a little better when cross module dependency exist. If the new feature or significant change is committed, please remember to add integration-test in test module.
  • Run mvn spotless:apply to format your code. Run mvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTests to make sure basic checks pass. Run mvn clean install to make sure unit-test pass. Run mvn clean test-compile failsafe:integration-test to make sure integration-test pass.

@github-actions

github-actions Bot commented Sep 1, 2026

Copy link
Copy Markdown

Thanks for your this PR. 🙏
Please check again for your PR changes whether contains any usage/api/configuration change such as Add new API , Add new configuration, Change default value of configuration.
If so, please add or update documents(markdown type) in docs/next/ for repository nacos-group/nacos-group.github.io


感谢您提交的PR。 🙏
请再次查看您的PR内容,确认是否包含任何使用方式/API/配置参数的变更,如:新增API、新增配置参数、修改默认配置等操作。
如果是,请确保在提交之前,在仓库nacos-group/nacos-group.github.io中的docs/next/目录下添加或更新文档(markdown格式)。

Move bundled Skill and AgentSpec seed archive parsing into their respective ZipParser classes while preserving bootstrap package metadata and limits.

Assisted-by: Claude Code
KomachiSion
KomachiSion previously approved these changes Sep 2, 2026
@codecov-commenter

codecov-commenter commented Sep 2, 2026 •

Copy link
Copy Markdown

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 nacos-community left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.unzipToEntries stores the normalized name; e.g. ./SKILL.md passes validation but then fails SKILL.md lookup downstream.
  • [Warning] ai/src/main/java/com/alibaba/nacos/ai/utils/SkillZipParser.java:719 — isIgnoredZipMetadataEntry is 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()));

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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()) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@KomachiSion KomachiSion added area/AI kind/bug Category issues or prs related to bug. labels Sep 7, 2026
@KomachiSion KomachiSion added this to the 3.3.0 milestone Sep 7, 2026
@KomachiSion
KomachiSion merged commit d98da48 into alibaba:develop Sep 7, 2026
7 of 9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/AI kind/bug Category issues or prs related to bug.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants