docs(skill): clarify ASAR inventory-first routing and provider selection (#10505)

* docs(skill): clarify ASAR inventory-first routing and provider selection

Document large-ASAR source_paths inventory, integrity_policy for re-signed
unpacked companions, and explicit provider_id when multiple deep providers
are configured.

Fixes #10501

* docs(skill): apply ASAR integrity policy during inventory

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
This commit is contained in:
Beqaandmorluto authored and GitHub committed 2026-11-19 05:20:32 +00:00
1 parent 48799e67c7
commit feedbaede7
4 files changed
+54 -4

No files matched your search

@@ -84,7 +84,13 @@ active-target native or archive workflows; target-free tools take their own
explicit path or endpoint and do not need it.
- ASAR or extracted JavaScript/Electron tree:
`analyze_javascript_application`.
`analyze_javascript_application`. To find a few files in a packaged
`app.asar`, open it with `open_binary`, start with `inspect_artifact`
using `detail: "summary"`, then analyze the selected files with
`source_paths`. When you intend to retain digest contradictions from
re-signed unpacked companions, pass `integrity_policy: "record-and-continue"`
starting with `inspect_artifact`. See the
[JavaScript applications reference](references/javascript-applications.md).
- Archive/package member inventory (ZIP/APK/IPA/MSIX/AppX, DMG, or a PyInstaller
executable): `open_binary` with the supplied local path; use `inspect_artifact`
when its graph and findings help answer the question. A PyInstaller CArchive
@@ -459,7 +465,12 @@ explicit path or endpoint and do not need it.
with an explicit path; portable, no active target or engine.
- Native executable, library, or analysis database: `open_binary`, then
use focused analysis tools directly; call `binary_overview` when metadata or
inventory context is useful and available from the selected provider.
inventory context is useful and available from the selected provider. If
automatic selection returns `capability_unavailable` with
`selection_reason: "ambiguous"`, several providers are usable for the
selected target. Choose one of the reported candidates and retry with its
`provider_id`. Without an active target, `binary_session({})` shows host
availability and leaves target support unknown.
For an existing IDA MCP configuration, use `open_binary` with the original
input binary and `provider_id: "ida"`; do not pass an `.idb` or `.i64` database.
@@ -23,6 +23,20 @@ question requires complete application analysis; `source_paths: []` is invalid,
not an unfiltered request. `detail: "summary"` reduces delivery
and does not by itself reduce analysis work.
To locate member paths in a packaged `app.asar`, call `open_binary` and
then `inspect_artifact` with `detail: "summary"`. Use
`normalized_result.parent_evidence_id` with `inspect_analysis_view` to find
member paths. Pass the selected paths as `source_paths` to
`analyze_javascript_application`. Narrowing the source selection reduces
analysis work. The inventory still examines the archive.
If unpacked companions differ from their declared digests after re-signing
and you intend to preserve those contradictions, pass
`integrity_policy: "record-and-continue"` to `inspect_artifact`,
`analyze_javascript_application`, and `extract_artifact` when you call them.
The default `fail` policy returns `artifact_integrity_mismatch` when an
operation encounters the contradiction, including the initial inventory.
ASAR header/index admission defaults to 16 MiB / 16777216 bytes;
an admission error names `asar.max_header_bytes` and its bounds (at most
256 MiB). Call `update_analysis_settings` with that setting, `action: "set"`
@@ -84,7 +84,13 @@ active-target native or archive workflows; target-free tools take their own
explicit path or endpoint and do not need it.
- ASAR or extracted JavaScript/Electron tree:
`analyze_javascript_application`.
`analyze_javascript_application`. To find a few files in a packaged
`app.asar`, open it with `open_binary`, start with `inspect_artifact`
using `detail: "summary"`, then analyze the selected files with
`source_paths`. When you intend to retain digest contradictions from
re-signed unpacked companions, pass `integrity_policy: "record-and-continue"`
starting with `inspect_artifact`. See the
[JavaScript applications reference](references/javascript-applications.md).
- Archive/package member inventory (ZIP/APK/IPA/MSIX/AppX, DMG, or a PyInstaller
executable): `open_binary` with the supplied local path; use `inspect_artifact`
when its graph and findings help answer the question. A PyInstaller CArchive
@@ -459,7 +465,12 @@ explicit path or endpoint and do not need it.
with an explicit path; portable, no active target or engine.
- Native executable, library, or analysis database: `open_binary`, then
use focused analysis tools directly; call `binary_overview` when metadata or
inventory context is useful and available from the selected provider.
inventory context is useful and available from the selected provider. If
automatic selection returns `capability_unavailable` with
`selection_reason: "ambiguous"`, several providers are usable for the
selected target. Choose one of the reported candidates and retry with its
`provider_id`. Without an active target, `binary_session({})` shows host
availability and leaves target support unknown.
For an existing IDA MCP configuration, use `open_binary` with the original
input binary and `provider_id: "ida"`; do not pass an `.idb` or `.i64` database.
@@ -23,6 +23,20 @@ question requires complete application analysis; `source_paths: []` is invalid,
not an unfiltered request. `detail: "summary"` reduces delivery
and does not by itself reduce analysis work.
To locate member paths in a packaged `app.asar`, call `open_binary` and
then `inspect_artifact` with `detail: "summary"`. Use
`normalized_result.parent_evidence_id` with `inspect_analysis_view` to find
member paths. Pass the selected paths as `source_paths` to
`analyze_javascript_application`. Narrowing the source selection reduces
analysis work. The inventory still examines the archive.
If unpacked companions differ from their declared digests after re-signing
and you intend to preserve those contradictions, pass
`integrity_policy: "record-and-continue"` to `inspect_artifact`,
`analyze_javascript_application`, and `extract_artifact` when you call them.
The default `fail` policy returns `artifact_integrity_mismatch` when an
operation encounters the contradiction, including the initial inventory.
ASAR header/index admission defaults to 16 MiB / 16777216 bytes;
an admission error names `asar.max_header_bytes` and its bounds (at most
256 MiB). Call `update_analysis_settings` with that setting, `action: "set"`