skilltotal 1.2.0__tar.gz → 1.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (104) hide show
  1. {skilltotal-1.2.0/skilltotal.egg-info → skilltotal-1.3.0}/PKG-INFO +6 -6
  2. {skilltotal-1.2.0 → skilltotal-1.3.0}/README.md +5 -5
  3. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/__init__.py +2 -2
  4. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/autorun.py +181 -1
  5. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/engine.py +114 -4
  6. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/file_index.py +97 -2
  7. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/loaded_code.py +10 -1
  8. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/models.py +1 -0
  9. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/owasp.py +5 -0
  10. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/__init__.py +6 -0
  11. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/agent_approval.py +31 -4
  12. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/agent_config.py +84 -10
  13. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/base.py +17 -7
  14. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/config_exec.py +13 -4
  15. skilltotal-1.3.0/skilltotal/scanners/dependency_source.py +273 -0
  16. skilltotal-1.3.0/skilltotal/scanners/disguised_script.py +219 -0
  17. skilltotal-1.3.0/skilltotal/scanners/env_inject.py +81 -0
  18. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/install_scripts.py +19 -95
  19. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/invisible_unicode.py +42 -14
  20. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/mcp.py +491 -39
  21. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/npm_supply.py +110 -6
  22. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/prompt_surface.py +92 -9
  23. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/secret_exfil.py +527 -34
  24. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/sensitive_paths.py +17 -1
  25. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/shell_exec.py +46 -22
  26. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/shell_script.py +308 -19
  27. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/skill_fetch_exec.py +25 -12
  28. skilltotal-1.3.0/skilltotal/text_normalize.py +497 -0
  29. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/traits.py +5 -0
  30. {skilltotal-1.2.0 → skilltotal-1.3.0/skilltotal.egg-info}/PKG-INFO +6 -6
  31. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal.egg-info/SOURCES.txt +3 -0
  32. skilltotal-1.2.0/skilltotal/text_normalize.py +0 -128
  33. {skilltotal-1.2.0 → skilltotal-1.3.0}/LICENSE +0 -0
  34. {skilltotal-1.2.0 → skilltotal-1.3.0}/MANIFEST.in +0 -0
  35. {skilltotal-1.2.0 → skilltotal-1.3.0}/pyproject.toml +0 -0
  36. {skilltotal-1.2.0 → skilltotal-1.3.0}/setup.cfg +0 -0
  37. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/__main__.py +0 -0
  38. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/accept.py +0 -0
  39. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/agent_adapters.py +0 -0
  40. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/agent_hook.py +0 -0
  41. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/agent_skill.py +0 -0
  42. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/baseline.py +0 -0
  43. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/bounded_json.py +0 -0
  44. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/capabilities.py +0 -0
  45. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/cli.py +0 -0
  46. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/collector.py +0 -0
  47. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/combinations.py +0 -0
  48. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/concat_normalize.py +0 -0
  49. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/config.py +0 -0
  50. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/diff.py +0 -0
  51. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/drift.py +0 -0
  52. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/guard.py +0 -0
  53. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/hook_fast.py +0 -0
  54. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/hook_scan.py +0 -0
  55. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/hook_setup.py +0 -0
  56. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/inventory.py +0 -0
  57. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/known_artifacts.py +0 -0
  58. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/mcp_server.py +0 -0
  59. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/node_interop.py +0 -0
  60. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/osv_lookup.py +0 -0
  61. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/parallel.py +0 -0
  62. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/plugin_sources.py +0 -0
  63. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/provenance.py +0 -0
  64. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/report.py +0 -0
  65. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/rules.py +0 -0
  66. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/sarif.py +0 -0
  67. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/sbom.py +0 -0
  68. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scan_cache.py +0 -0
  69. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/artifact_provenance.py +0 -0
  70. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/clipper.py +0 -0
  71. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/dependency_redirect.py +0 -0
  72. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/dynamic_code.py +0 -0
  73. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/email_exfil.py +0 -0
  74. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/encrypted_archive.py +0 -0
  75. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/exposure.py +0 -0
  76. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/fetch_tunnel_launcher.py +0 -0
  77. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/filesystem.py +0 -0
  78. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/html_file_exfil.py +0 -0
  79. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/install_payload.py +0 -0
  80. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/mcp_annotations.py +0 -0
  81. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/mcp_elicitation.py +0 -0
  82. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/mcp_pinning.py +0 -0
  83. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/network.py +0 -0
  84. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/npm_install_threats.py +0 -0
  85. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/oauth_auth.py +0 -0
  86. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/oauth_discovery.py +0 -0
  87. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/obfuscation.py +0 -0
  88. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/postex.py +0 -0
  89. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/pth_exec.py +0 -0
  90. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/pypi_malware.py +0 -0
  91. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/python_ast.py +0 -0
  92. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/scoped_identity.py +0 -0
  93. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/secrets.py +0 -0
  94. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/shell_evasion.py +0 -0
  95. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/skill_directives.py +0 -0
  96. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/stdlib_shadow.py +0 -0
  97. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scanners/workflow_exfil.py +0 -0
  98. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/scoring.py +0 -0
  99. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/sentinel.py +0 -0
  100. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal/typosquatting.py +0 -0
  101. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal.egg-info/dependency_links.txt +0 -0
  102. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal.egg-info/entry_points.txt +0 -0
  103. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal.egg-info/requires.txt +0 -0
  104. {skilltotal-1.2.0 → skilltotal-1.3.0}/skilltotal.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: skilltotal
3
- Version: 1.2.0
3
+ Version: 1.3.0
4
4
  Summary: Static security scanner for npm and PyPI packages, MCP servers and agent skills. Runs locally, never runs the code, no LLM.
5
5
  Author: SkillTotal
6
6
  License-Expression: Apache-2.0
@@ -104,7 +104,7 @@ skilltotal scan npm:express # or pypi:name, a git URL, a folder, an archive
104
104
  ([full example with permissions](https://github.com/pezhik/skilltotal/blob/main/docs/ci.md)):
105
105
 
106
106
  ```yaml
107
- - uses: pezhik/skilltotal@v1.2.0
107
+ - uses: pezhik/skilltotal@v1.3.0
108
108
  with: { source: ., fail-on: high }
109
109
  ```
110
110
 
@@ -280,7 +280,7 @@ Jenkins and rolling out on an existing repository. Anywhere else Python 3.10+ ru
280
280
  on the exit code (0 passed, 2 a gate tripped, 1 the scan could not run):
281
281
 
282
282
  ```bash
283
- pip install skilltotal==1.2.0 # in a virtual environment outside the checkout
283
+ pip install skilltotal==1.3.0 # in a virtual environment outside the checkout
284
284
  skilltotal scan . --fail-on high
285
285
  ```
286
286
 
@@ -344,14 +344,14 @@ With npx (it needs uv, pipx, or Python 3.11+ with `skilltotal` installed), name
344
344
  `--package` so npx does not run a `skilltotal` from the scanned repository's `node_modules/.bin`:
345
345
 
346
346
  ```bash
347
- npx -y --package=skilltotal@1.2.0 -- skilltotal scan https://github.com/owner/repo
347
+ npx -y --package=skilltotal@1.3.0 -- skilltotal scan https://github.com/owner/repo
348
348
  ```
349
349
 
350
350
  ## Measured, not asserted
351
351
 
352
352
  - **[Detection efficacy](https://github.com/pezhik/skilltotal/blob/main/docs/efficacy-report.md)**:
353
- recall and precision on a labeled corpus we built and publish (240 malicious and
354
- 200 benign samples), regenerated every release and enforced by CI as a floor. A perfect score on
353
+ recall and precision on a labeled corpus we built and publish (308 malicious and
354
+ 239 benign samples), regenerated every release and enforced by CI as a floor. A perfect score on
355
355
  our own corpus guards against regressions; it is not a claim about every attack in the wild.
356
356
  Each rule behind the survey's OWASP class counts also has labeled samples of its own, listed in
357
357
  the report's rule coverage table.
@@ -61,7 +61,7 @@ skilltotal scan npm:express # or pypi:name, a git URL, a folder, an archive
61
61
  ([full example with permissions](https://github.com/pezhik/skilltotal/blob/main/docs/ci.md)):
62
62
 
63
63
  ```yaml
64
- - uses: pezhik/skilltotal@v1.2.0
64
+ - uses: pezhik/skilltotal@v1.3.0
65
65
  with: { source: ., fail-on: high }
66
66
  ```
67
67
 
@@ -237,7 +237,7 @@ Jenkins and rolling out on an existing repository. Anywhere else Python 3.10+ ru
237
237
  on the exit code (0 passed, 2 a gate tripped, 1 the scan could not run):
238
238
 
239
239
  ```bash
240
- pip install skilltotal==1.2.0 # in a virtual environment outside the checkout
240
+ pip install skilltotal==1.3.0 # in a virtual environment outside the checkout
241
241
  skilltotal scan . --fail-on high
242
242
  ```
243
243
 
@@ -301,14 +301,14 @@ With npx (it needs uv, pipx, or Python 3.11+ with `skilltotal` installed), name
301
301
  `--package` so npx does not run a `skilltotal` from the scanned repository's `node_modules/.bin`:
302
302
 
303
303
  ```bash
304
- npx -y --package=skilltotal@1.2.0 -- skilltotal scan https://github.com/owner/repo
304
+ npx -y --package=skilltotal@1.3.0 -- skilltotal scan https://github.com/owner/repo
305
305
  ```
306
306
 
307
307
  ## Measured, not asserted
308
308
 
309
309
  - **[Detection efficacy](https://github.com/pezhik/skilltotal/blob/main/docs/efficacy-report.md)**:
310
- recall and precision on a labeled corpus we built and publish (240 malicious and
311
- 200 benign samples), regenerated every release and enforced by CI as a floor. A perfect score on
310
+ recall and precision on a labeled corpus we built and publish (308 malicious and
311
+ 239 benign samples), regenerated every release and enforced by CI as a floor. A perfect score on
312
312
  our own corpus guards against regressions; it is not a claim about every attack in the wild.
313
313
  Each rule behind the survey's OWASP class counts also has labeled samples of its own, listed in
314
314
  the report's rule coverage table.
@@ -40,10 +40,10 @@ def __getattr__(name: str) -> object:
40
40
  # REPORT_SCHEMA_VERSION: shape of Report.to_dict(); bumps only on schema changes.
41
41
  # RULESET_VERSION: integer counter of the detection ruleset; bumps when rules change, so a
42
42
  # consumer knows when re-scanning old reports may surface new findings.
43
- __version__ = "1.2.0"
43
+ __version__ = "1.3.0"
44
44
  ENGINE_VERSION = __version__
45
45
  REPORT_SCHEMA_VERSION = "1.11"
46
- RULESET_VERSION = 101
46
+ RULESET_VERSION = 102
47
47
 
48
48
  __all__ = [
49
49
  "__version__",
@@ -15,7 +15,12 @@ without a separate step from the user:
15
15
  folder opens;
16
16
  * a Claude Code plugin: its hooks, background monitors and language servers, inline in
17
17
  ``plugin.json``, in a marketplace entry or in their default files;
18
- * hooks in the frontmatter of a skill or a subagent.
18
+ * hooks in the frontmatter of a skill or a subagent;
19
+ * a dev container's lifecycle commands (``devcontainer.json``): ``initializeCommand`` runs on the
20
+ host when the folder is opened in a container, the others inside the container;
21
+ * an ``env`` block of Claude Code settings or of an MCP or language server whose variable makes
22
+ every process started with it load a file or run a command first (``NODE_OPTIONS=--require``,
23
+ ``LD_PRELOAD``, ``BASH_ENV``, ``GIT_SSH_COMMAND``, ...).
19
24
 
20
25
  This module only reads them: one list of :class:`AutorunCommand` per index (cached), which the
21
26
  scanners judge (``agent_config`` for fetch-and-run and honest auto-run configuration,
@@ -40,6 +45,9 @@ ORIGIN_PROJECT = "project" # project settings, editor tasks: runs when the fold
40
45
  ORIGIN_PLUGIN = "plugin" # a plugin's own hooks, monitors and language servers
41
46
  ORIGIN_MCP = "mcp" # an MCP server launch command, in any client's configuration
42
47
  ORIGIN_SKILL = "skill" # hooks in the frontmatter of a skill or a subagent
48
+ # A dev container hook that runs inside the container: honest ones install toolchains there.
49
+ ORIGIN_CONTAINER = "container"
50
+ ORIGIN_ENV = "env" # the value of a code-injecting environment variable (see EnvInjection)
43
51
 
44
52
  KIND_HOOK = "hook"
45
53
  KIND_HTTP_HOOK = "http_hook"
@@ -50,6 +58,8 @@ KIND_MCP_SERVER = "mcp_server"
50
58
  KIND_HEADERS_HELPER = "headers_helper"
51
59
  KIND_MONITOR = "monitor"
52
60
  KIND_LSP_SERVER = "lsp_server"
61
+ KIND_CONTAINER_HOOK = "container_hook"
62
+ KIND_ENV = "env"
53
63
 
54
64
  # Agent hook files whose commands run when a session starts or a tool runs, with no further step.
55
65
  _PROJECT_HOOK_FILES = (
@@ -71,6 +81,13 @@ _PLUGIN_MONITORS = "monitors/monitors.json"
71
81
  _PLUGIN_LSP = ".lsp.json"
72
82
  _VSCODE_TASKS = ".vscode/tasks.json"
73
83
  _VSCODE_SETTINGS = ".vscode/settings.json"
84
+ # Dev container lifecycle commands. `initializeCommand` runs on the host machine; the rest run
85
+ # inside the container once it exists.
86
+ _DEVCONTAINER_HOST_KEYS = ("initializeCommand",)
87
+ _DEVCONTAINER_CONTAINER_KEYS = (
88
+ "onCreateCommand", "updateContentCommand", "postCreateCommand", "postStartCommand",
89
+ "postAttachCommand",
90
+ )
74
91
  # The file names the MCP scanner reads as manifests (scanners/mcp.py MANIFEST_NAMES).
75
92
  _MCP_MANIFEST_NAMES = frozenset(
76
93
  {"mcp.json", ".mcp.json", "mcp.config.json", "server.json", "manifest.json"}
@@ -133,10 +150,32 @@ class AutorunCommand:
133
150
  return self.file.evidence_for_span(piece.start, max(piece.start + 1, piece.end))
134
151
 
135
152
 
153
+ @dataclass(frozen=True, eq=False)
154
+ class EnvInjection:
155
+ """An ``env`` entry of shipped agent or server configuration whose variable makes each process
156
+ started with it load a file or run a command before its own code."""
157
+
158
+ name: str # the variable, upper case
159
+ origin: str # ORIGIN_PROJECT for agent settings, else the origin of the server it belongs to
160
+ file: IndexedFile
161
+ value: Piece
162
+ # The language the loaded file is read as (".js", ".sh", ".py"); "" when the variable holds a
163
+ # command or loads native code.
164
+ language: str = ""
165
+ # Relative paths inside the component the value may name (the first that exists is loaded).
166
+ paths: tuple[str, ...] = ()
167
+
168
+ def evidence(self) -> Evidence:
169
+ return self.file.evidence_for_span(
170
+ self.value.start, max(self.value.start + 1, self.value.end)
171
+ )
172
+
173
+
136
174
  @dataclass(frozen=True, eq=False)
137
175
  class AutorunScan:
138
176
  commands: tuple[AutorunCommand, ...] = ()
139
177
  reviews: tuple[NeedsReview, ...] = ()
178
+ env_injections: tuple[EnvInjection, ...] = ()
140
179
  # Markdown files (skills, subagents) whose frontmatter declares hooks or MCP servers, mapped to
141
180
  # the last line of that frontmatter: those lines are configuration the tool runs, not
142
181
  # documentation, whatever the file's name says (its body is still prose).
@@ -171,10 +210,71 @@ def _scan(index: FileIndex) -> AutorunScan:
171
210
  return AutorunScan(
172
211
  commands=tuple(out.commands),
173
212
  reviews=tuple(out.reviews),
213
+ env_injections=tuple(out.env_injections),
174
214
  frontmatter_lines=dict(out.frontmatter_lines),
175
215
  )
176
216
 
177
217
 
218
+ # ------------------------------------------------------------- code-injecting environment
219
+ # Variables whose value is a file the dynamic loader maps into every process (native code).
220
+ _ENV_NATIVE_PRELOAD = frozenset({"LD_PRELOAD", "DYLD_INSERT_LIBRARIES"})
221
+ # Variables whose value is a script an interpreter runs before anything else, and its language.
222
+ _ENV_STARTUP_FILE = {"BASH_ENV": ".sh", "PYTHONSTARTUP": ".py"}
223
+ # Variables whose value is a command line another program runs (git for every ssh remote, Claude
224
+ # Code in front of every shell command).
225
+ _ENV_COMMAND = frozenset({"GIT_SSH_COMMAND", "CLAUDE_CODE_SHELL_PREFIX"})
226
+ # `NODE_OPTIONS` flags that load a module into every Node.js process before its own code.
227
+ _NODE_PRELOAD = re.compile(
228
+ r"(?<![\w-])(?:--require|-r|--import|--loader|--experimental-loader)(?:=|[ \t]+)"
229
+ r"[\"']?([^\s\"']{1,400})"
230
+ )
231
+ # A module given as a path (not a package name such as `dotenv/config` or `tsx`, which loads an
232
+ # installed dependency and is what honest tooling sets).
233
+ _PATH_SHAPED = re.compile(r"^(?:\.{1,2}[/\\]|[/\\~$]|[A-Za-z]:[/\\]|file:)|\.(?:[cm]?js|ts|node)$")
234
+ _ENV_ROOT_VARIABLE = re.compile(r"^(?:\$\{?[A-Za-z_][\w:.-]*\}?[/\\])+")
235
+ _MAX_ENV_INJECTIONS = 200
236
+
237
+
238
+ def _env_injection(name: str, value: str) -> tuple[str, tuple[str, ...]] | None:
239
+ """``(language, path words)`` when ``name=value`` injects code into the processes started with
240
+ it, else None. An empty value, a ``NODE_OPTIONS`` without a preload flag (heap size, warnings)
241
+ and a preload of an installed package by name are not injections."""
242
+ name = name.upper()
243
+ value = value.strip()
244
+ if not value:
245
+ return None
246
+ if name in _ENV_NATIVE_PRELOAD:
247
+ return "", tuple(w for w in re.split(r"[\s:;]+", value) if w)
248
+ if name in _ENV_STARTUP_FILE:
249
+ return _ENV_STARTUP_FILE[name], (value.strip("\"'"),)
250
+ if name in _ENV_COMMAND:
251
+ return "", ()
252
+ if name == "NODE_OPTIONS":
253
+ words = tuple(
254
+ m.group(1) for m in _NODE_PRELOAD.finditer(value) if _PATH_SHAPED.search(m.group(1))
255
+ )
256
+ return (".js", words) if words else None
257
+ return None
258
+
259
+
260
+ def _component_paths(words: tuple[str, ...], near: str) -> tuple[str, ...]:
261
+ """Relative paths inside the component that ``words`` may name: from the component root and
262
+ from each folder above ``near`` (the file that holds them). A word that leaves the component,
263
+ or is absolute, names nothing here."""
264
+ parts = near.replace("\\", "/").split("/")[:-1]
265
+ folders = [""] + ["/".join(parts[:k]) for k in range(len(parts), 0, -1)]
266
+ out: list[str] = []
267
+ for word in words:
268
+ word = _ENV_ROOT_VARIABLE.sub("", word.removeprefix("file:")).replace("\\", "/")
269
+ if not word or word.startswith(("/", "~")) or ":" in word or "\x00" in word:
270
+ continue
271
+ for folder in folders:
272
+ rel = normpath(f"{folder}/{word}" if folder else word)
273
+ if rel != "." and not rel.startswith("../") and rel != ".." and rel not in out:
274
+ out.append(rel)
275
+ return tuple(out)
276
+
277
+
178
278
  class _Anchors:
179
279
  """Where each string value is written in a file, found once per occurrence in order."""
180
280
 
@@ -207,6 +307,7 @@ class _Collector:
207
307
  self.commands: list[AutorunCommand] = []
208
308
  self.reviews: list[NeedsReview] = []
209
309
  self.frontmatter_lines: dict[str, int] = {}
310
+ self.env_injections: list[EnvInjection] = []
210
311
  self._parsed: dict[str, object] = {}
211
312
 
212
313
  # -- JSON ---------------------------------------------------------------------------------
@@ -220,6 +321,7 @@ class _Collector:
220
321
  hook_file or plugin_file
221
322
  or lower.endswith((_VSCODE_TASKS, _VSCODE_SETTINGS))
222
323
  or name in ("mcp.json", "manifest.json")
324
+ or _is_devcontainer(lower, name)
223
325
  or '"mcpServers"' in text
224
326
  # A key written with escapes (`"mcp\u0053ervers"`) is the same name to a JSON
225
327
  # reader, so a file with any escape is parsed and its decoded keys decide.
@@ -235,6 +337,9 @@ class _Collector:
235
337
  self._hooks(f, anchors, data.get("hooks"), ORIGIN_PROJECT)
236
338
  if lower.endswith(_CLAUDE_SETTINGS):
237
339
  self._settings_commands(f, anchors, data, ORIGIN_PROJECT)
340
+ self._env(f, anchors, data.get("env"), ORIGIN_PROJECT)
341
+ if _is_devcontainer(lower, name) and isinstance(data, dict):
342
+ self._devcontainer(f, anchors, data)
238
343
  if lower.endswith(_VSCODE_TASKS) and isinstance(data, dict):
239
344
  self._folder_open_tasks(f, anchors, data)
240
345
  if isinstance(data, dict):
@@ -354,6 +459,44 @@ class _Collector:
354
459
  elif isinstance(node, list):
355
460
  stack.append(iter(node))
356
461
 
462
+ def _env(self, f: IndexedFile, anchors: _Anchors, env: object, origin: str) -> None:
463
+ """The entries of an ``env`` map that inject code (``_env_injection``). Each is recorded,
464
+ and its value is also a command of its own (``KIND_ENV``): a command line it holds, or
465
+ the path of the script it loads, gets the checks every auto-run command gets."""
466
+ if not isinstance(env, dict):
467
+ return
468
+ for name, value in env.items():
469
+ if len(self.env_injections) >= _MAX_ENV_INJECTIONS:
470
+ return
471
+ if not isinstance(name, str) or not isinstance(value, str):
472
+ continue
473
+ injected = _env_injection(name, value)
474
+ if injected is None:
475
+ continue
476
+ language, words = injected
477
+ piece = anchors.piece(value, name)
478
+ self.env_injections.append(EnvInjection(
479
+ name=name.upper(), origin=origin, file=f, value=piece, language=language,
480
+ paths=_component_paths(words, f.relpath),
481
+ ))
482
+ self.commands.append(AutorunCommand(
483
+ kind=KIND_ENV, origin=ORIGIN_ENV, file=f, pieces=(piece,), container="env",
484
+ ))
485
+
486
+ def _devcontainer(self, f: IndexedFile, anchors: _Anchors, data: dict) -> None:
487
+ """A dev container's lifecycle commands: a string (run by a shell), a list (a program and
488
+ its arguments) or a map of named commands of either form, which run side by side."""
489
+ keys = [(k, KIND_TASK, ORIGIN_PROJECT) for k in _DEVCONTAINER_HOST_KEYS]
490
+ keys += [(k, KIND_CONTAINER_HOOK, ORIGIN_CONTAINER) for k in _DEVCONTAINER_CONTAINER_KEYS]
491
+ for key, kind, origin in keys:
492
+ value = data.get(key)
493
+ for command in (value.values() if isinstance(value, dict) else (value,)):
494
+ if isinstance(command, str):
495
+ self._entry(kind, origin, f, anchors, command, key=key, container=key)
496
+ elif isinstance(command, list) and command:
497
+ self._entry(kind, origin, f, anchors, command[0], command[1:], key=key,
498
+ container=key)
499
+
357
500
  def _settings_commands(
358
501
  self, f: IndexedFile, anchors: _Anchors, data: dict, origin: str
359
502
  ) -> None:
@@ -380,6 +523,7 @@ class _Collector:
380
523
  ) -> None:
381
524
  self._entry(KIND_MCP_SERVER, origin, f, anchors, server.get("command"), server.get("args"),
382
525
  server.get("env"), container=container)
526
+ self._env(f, anchors, server.get("env"), origin)
383
527
  helper = server.get("headersHelper")
384
528
  if isinstance(helper, str):
385
529
  self._entry(KIND_HEADERS_HELPER, origin, f, anchors, helper, key="headersHelper",
@@ -397,6 +541,7 @@ class _Collector:
397
541
  if isinstance(server, dict):
398
542
  self._entry(KIND_LSP_SERVER, ORIGIN_PLUGIN, f, anchors, server.get("command"),
399
543
  server.get("args"), server.get("env"), container="lspServers")
544
+ self._env(f, anchors, server.get("env"), ORIGIN_PLUGIN)
400
545
 
401
546
  def _monitors(self, f: IndexedFile, anchors: _Anchors, monitors: list) -> None:
402
547
  for monitor in monitors:
@@ -527,6 +672,14 @@ class _Collector:
527
672
  self.frontmatter_lines[f.relpath] = f.line_of_offset(last.start + len(last.text)) + 1
528
673
 
529
674
 
675
+ def _is_devcontainer(lower: str, name: str) -> bool:
676
+ """``.devcontainer.json``, ``.devcontainer/devcontainer.json`` or
677
+ ``.devcontainer/<name>/devcontainer.json`` (``lower`` is the lower-cased relative path)."""
678
+ if name == ".devcontainer.json":
679
+ return True
680
+ return name == "devcontainer.json" and ".devcontainer" in lower.split("/")[-3:-1]
681
+
682
+
530
683
  def _as_list(value: object) -> list:
531
684
  if value is None:
532
685
  return []
@@ -802,6 +955,33 @@ def _frontmatter_lines(text: str) -> tuple[list[_Line], bool]:
802
955
  return lines, pos < end.start()
803
956
 
804
957
 
958
+ def frontmatter_values(text: str) -> list[tuple[str, str, int, int]]:
959
+ """``(key, value, start, end)`` for each top-level key of a markdown file's leading YAML
960
+ frontmatter: a scalar written on the key's line, and each item of a block list under it
961
+ (``allowed-tools:`` followed by ``- Bash(*)`` lines). Offsets are into ``text``. Nested maps
962
+ are passed over; a flow value (``[a, b]``, ``a, b``) is returned whole."""
963
+ lines, _cut = _frontmatter_lines(text)
964
+ out: list[tuple[str, str, int, int]] = []
965
+ key = ""
966
+ for line in lines:
967
+ stripped = line.text.strip()
968
+ if not stripped or stripped.startswith("#"):
969
+ continue
970
+ if line.indent == 0 and not stripped.startswith("-"):
971
+ m = _YAML_KEY.match(line.text)
972
+ key = m.group(2) if m else ""
973
+ raw = (m.group(3) or "") if m else ""
974
+ if m and raw.strip() and not _BLOCK_SCALAR.match(raw.strip()):
975
+ value, start, end = _yaml_scalar(raw, line.start + m.start(3))
976
+ out.append((key, value, start, end))
977
+ elif key and stripped.startswith("-"):
978
+ at = line.text.index("-") + 1
979
+ value, start, end = _yaml_scalar(line.text[at:], line.start + at)
980
+ if value:
981
+ out.append((key, value, start, end))
982
+ return out
983
+
984
+
805
985
  def _yaml_scalar(raw: str, offset: int) -> tuple[str, int, int]:
806
986
  """A plain or quoted YAML scalar written on one line, decoded, with its file offsets."""
807
987
  stripped = raw.strip()
@@ -51,6 +51,7 @@ from skilltotal.loaded_code import LOADING_SUFFIXES as _LOADING_SUFFIXES
51
51
  from skilltotal.loaded_code import (
52
52
  MAX_LOADED_FILES,
53
53
  NPM_LIFECYCLE_SCRIPTS,
54
+ _inside_by_name,
54
55
  follow_skipped_references,
55
56
  install_time_scripts,
56
57
  )
@@ -84,6 +85,11 @@ from skilltotal.scan_cache import ScanCache
84
85
  from skilltotal.scanners import SCANNERS
85
86
  from skilltotal.scanners.artifact_provenance import prebuilt_artifacts
86
87
  from skilltotal.scanners.base import MAX_EVIDENCE_PER_FINDING, aggregated_review
88
+ from skilltotal.scanners.disguised_script import (
89
+ DISGUISE_SUFFIXES,
90
+ SOURCE_INSTALL,
91
+ disguised_runs,
92
+ )
87
93
  from skilltotal.scanners.mcp import is_mcp_listing
88
94
  from skilltotal.scoring import compute_score, is_own_provider_read, risk_level
89
95
  from skilltotal.traits import build_trait_profile
@@ -205,7 +211,8 @@ def analyze_directory(
205
211
  index = build_index(entry_points)
206
212
  # The file an MCP manifest launches is an entry point too. It is known only once the manifests
207
213
  # are read; one the walk set aside for its shape or size is read on a second walk (rare).
208
- launched = _mcp_launched_files(index) - entry_points
214
+ # So is a file an `env` block makes every process load (`NODE_OPTIONS=--require ./x.js`).
215
+ launched = (_mcp_launched_files(index) | _env_loaded_files(index)) - entry_points
209
216
  if launched & {*index.minified, *index.large}:
210
217
  index = build_index(entry_points | launched)
211
218
  entry_points |= launched
@@ -216,7 +223,20 @@ def analyze_directory(
216
223
  ) if bundled else frozenset()
217
224
  # Code the component loads by a literal path from a folder the walk passed over (its own
218
225
  # `lib/env/`, `src/vendor/`, ...) is read too: it runs whatever folder it is filed under.
219
- index, unloaded = follow_skipped_references(index)
226
+ index, unloaded = follow_skipped_references(index, _env_loaded_paths(index))
227
+ # A file started under a name that hides it (`node assets/logo.png`, `python3 x.docx`) is read
228
+ # as the language it is started in, and is an entry point like any file a command starts.
229
+ disguised = disguised_runs(index, _component_file_check(Path(root)))
230
+ languages = {run.target: run.language for run in disguised if run.read}
231
+ languages.update(_env_loaded_languages(index))
232
+ if languages:
233
+ index = index.reading_as(languages)
234
+ # A command written in a fixture (a test, an example, a corpus sample) starts nothing
235
+ # for whoever installs the component, so what it names stays with that folder's rules.
236
+ entry_points |= {
237
+ run.target for run in disguised
238
+ if run.read and not _is_fixture_file(run.evidence.file)
239
+ }
220
240
 
221
241
  findings: list[Finding] = []
222
242
  needs_review: list[NeedsReview] = []
@@ -262,6 +282,23 @@ def analyze_directory(
262
282
  ))
263
283
  if unloaded:
264
284
  needs_review.append(_unloaded_note(unloaded))
285
+ # A file a command starts under a name that hides it, which is not text the scan reads: it
286
+ # is started all the same. One an install command starts already has the install note above.
287
+ unread_started = sorted({
288
+ run.target for run in disguised
289
+ if not run.read and not (run.source == SOURCE_INSTALL and run.target in install_scripts)
290
+ })
291
+ if unread_started:
292
+ needs_review.append(aggregated_review(
293
+ category="coverage",
294
+ title="Started file not analyzed",
295
+ places=[(p, None) for p in unread_started],
296
+ what="file(s) named like an image, a document or data are started with an "
297
+ "interpreter by an instruction file or an auto-run command, and could not be "
298
+ "read as text",
299
+ advice="They are run as code, and nothing in them was checked. Read them, or treat "
300
+ "the component as unverified.",
301
+ ))
265
302
  skipped_note = _skipped_folders_note(index)
266
303
  if skipped_note is not None:
267
304
  needs_review.append(skipped_note)
@@ -619,7 +656,9 @@ def _install_script_files(root: Path, limits: list[str] | None = None) -> dict[s
619
656
  reached.append(f"{_MAX_INSTALL_WORDS} words of the {script} command")
620
657
  for word in words:
621
658
  target = _module_file(base, package, word)
622
- if target is not None:
659
+ # A manifest a command only names (`cp package.json dist/`, `node -p
660
+ # "require('./package.json').version"`) is data, not a script the command starts.
661
+ if target is not None and target.name != "package.json":
623
662
  queue.append((target, script, package))
624
663
  while queue:
625
664
  if len(found) >= _MAX_INSTALL_FILES:
@@ -628,7 +667,9 @@ def _install_script_files(root: Path, limits: list[str] | None = None) -> dict[s
628
667
  break
629
668
  target, script, package = queue.pop(0)
630
669
  relpath = target.relative_to(base).as_posix()
631
- if relpath in found:
670
+ if relpath in found or target.name == "package.json":
671
+ # A manifest an install-run file loads for its version (`require("../package.json")`)
672
+ # is data. Its own scripts are judged by their names, not as a script that ran.
632
673
  continue
633
674
  found[relpath] = script
634
675
  suffix = target.suffix.lower()
@@ -998,6 +1039,75 @@ def _mcp_launched_files(index: FileIndex) -> set[str]:
998
1039
  return found
999
1040
 
1000
1041
 
1042
+ def _is_fixture_file(relpath: str) -> bool:
1043
+ """Whether a configuration, manifest or instruction file is a fixture of the component (a
1044
+ test, an example, a document, a corpus sample, CI) and not something it ships to be used: a
1045
+ command written there runs for nobody who installs the component. An instruction file is
1046
+ markdown by nature, so only its folder can make it a document."""
1047
+ return (
1048
+ is_test_path(relpath) or is_example_path(relpath) or is_data_corpus_path(relpath)
1049
+ or is_ci_path(relpath)
1050
+ or (not relpath.lower().endswith((".md", ".mdx")) and is_doc_path(relpath))
1051
+ )
1052
+
1053
+
1054
+ def _env_loaded_paths(index: FileIndex) -> list[str]:
1055
+ """Relative paths that an `env` block of shipped agent or server configuration may load code
1056
+ from (``autorun.EnvInjection.paths``), whether or not the walk read them."""
1057
+ return [
1058
+ path for inj in autorun_commands(index).env_injections
1059
+ if not _is_fixture_file(inj.file.relpath) for path in inj.paths
1060
+ ]
1061
+
1062
+
1063
+ def _env_loaded_files(index: FileIndex) -> set[str]:
1064
+ """The files of the component an `env` block makes every process load
1065
+ (``NODE_OPTIONS=--require ./tools/shim.js``, ``BASH_ENV=./.claude/env.sh``): the first path of
1066
+ each entry that names a file the walk found. They run as surely as a declared entry point."""
1067
+ known = {f.relpath for f in index.files} | set(index.minified) | set(index.large)
1068
+ found: set[str] = set()
1069
+ for injection in autorun_commands(index).env_injections:
1070
+ if _is_fixture_file(injection.file.relpath):
1071
+ continue
1072
+ loaded = next((path for path in injection.paths if path in known), None)
1073
+ if loaded is not None and len(found) < _MAX_ENTRY_POINTS:
1074
+ found.add(loaded)
1075
+ return found
1076
+
1077
+
1078
+ def _env_loaded_languages(index: FileIndex) -> dict[str, str]:
1079
+ """``{relative path: language suffix}`` for each file an `env` block loads as a script while
1080
+ its name says it is an image, a document or data (``BASH_ENV=./assets/banner.png``)."""
1081
+ known = {f.relpath for f in index.files}
1082
+ out: dict[str, str] = {}
1083
+ for injection in autorun_commands(index).env_injections:
1084
+ loaded = next((path for path in injection.paths if path in known), None)
1085
+ if (loaded is not None and injection.language
1086
+ and posixpath.splitext(loaded)[1].lower() in DISGUISE_SUFFIXES):
1087
+ out[loaded] = injection.language
1088
+ return out
1089
+
1090
+
1091
+ # How many paths a scan looks up on disk for files started under a hiding name.
1092
+ _MAX_STARTED_LOOKUPS = 64
1093
+
1094
+
1095
+ def _component_file_check(root: Path) -> Callable[[str], bool]:
1096
+ """A test for "this relative path is a regular file inside the component", by name first so
1097
+ that nothing outside it is touched; at most ``_MAX_STARTED_LOOKUPS`` paths are looked up."""
1098
+ base = root.resolve()
1099
+ looked_up: dict[str, bool] = {}
1100
+
1101
+ def exists(rel: str) -> bool:
1102
+ if rel not in looked_up:
1103
+ if len(looked_up) >= _MAX_STARTED_LOOKUPS or not _inside_by_name(base, base, rel):
1104
+ return False
1105
+ looked_up[rel] = is_regular_file(base / rel)
1106
+ return looked_up[rel]
1107
+
1108
+ return exists
1109
+
1110
+
1001
1111
  def _package_manifests(root: Path) -> list[Path]:
1002
1112
  """The ``package.json`` files whose install scripts count: the component's own, then those
1003
1113
  of packages inside it, outside skipped folders and outside test, example, documentation,