Skip to content

Commit 383077e

Browse files
authored
Merge pull request #601 from efegokdemir/codex/issue-585-declaration-executable
fix: inspect TypeScript declaration content
2 parents 1a5e08c + 18fe8e8 commit 383077e

4 files changed

Lines changed: 242 additions & 6 deletions

File tree

‎src/skillspector/nested_artifacts.py‎

Lines changed: 108 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
from __future__ import annotations
1313

1414
import io
15+
import re
1516
import stat
1617
import struct
1718
import time
@@ -389,21 +390,124 @@ def _zip_member_is_link(info: zipfile.ZipInfo) -> bool:
389390
b"\xbf\xba\xfe\xca",
390391
)
391392

393+
_TYPESCRIPT_DECLARATION_SUFFIXES = (".d.ts", ".d.cts", ".d.mts")
394+
_TYPESCRIPT_AMBIENT_MEMBER = (
395+
r"(?:export\s+)?(?:"
396+
r"interface\s+[A-Za-z_$][\w$]*(?:\s*<[^\r\n{}]*>)?\s*\{[^\r\n{}]*\}|"
397+
r"type\s+[A-Za-z_$][\w$]*(?:\s*<[^\r\n;{}]*>)?\s*=\s*[^\r\n;{}]+;|"
398+
r"(?:const|let|var)\s+[A-Za-z_$][\w$]*(?:\s*:\s*[^\r\n;{}]+)?\s*;|"
399+
r"function\s+[A-Za-z_$][\w$]*\s*\([^\r\n{}]*\)\s*:\s*[^\r\n;{}]+;|"
400+
r"class\s+[A-Za-z_$][\w$]*\s*\{[^\r\n{}]*\}"
401+
r")"
402+
)
403+
_TYPESCRIPT_DECLARATION_FILE = re.compile(
404+
r"\A\s*(?:(?:"
405+
r"(?:(?:export\s+)?declare\s+(?:const|let|var|function|class)\b[^\r\n;{}]*;)|"
406+
rf"(?:declare\s+(?:export\s+)?namespace\s+[A-Za-z_$][\w$]*\s*\{{(?:\s*{_TYPESCRIPT_AMBIENT_MEMBER})*\s*\}}\s*;?)|"
407+
rf"(?:declare\s+module\s+(?:[\"'][^\"']+[\"']|[A-Za-z_$][\w$]*)\s*\{{(?:\s*{_TYPESCRIPT_AMBIENT_MEMBER})*\s*\}}\s*;?)|"
408+
r"(?:(?:export\s+)?interface\s+[A-Za-z_$][\w$]*(?:\s*<[^\r\n{}]*>)?\s*\{[^\r\n{}]*\}\s*;?)|"
409+
r"(?:(?:export\s+)?type\s+[A-Za-z_$][\w$]*(?:\s*<[^;{}]*>)?\s*=\s*[^;\r\n{}]+;)|"
410+
r"(?:import\s+type\s+(?:[A-Za-z_$][\w$]*(?:\s*,\s*\{[^{}]*\})?|\{[^{}]*\}|\*\s+as\s+[A-Za-z_$][\w$]*)\s+from\s+[\"'][^\"'\r\n]+[\"']\s*;)|"
411+
r"(?:export\s*\{[^{}]*\}\s*;?)"
412+
r")\s*)+\Z",
413+
re.DOTALL,
414+
)
415+
416+
417+
def _strip_typescript_comments(text: str) -> str | None:
418+
"""Remove comments without interpreting comment markers inside literals."""
419+
result: list[str] = []
420+
index = 0
421+
while index < len(text):
422+
character = text[index]
423+
if character in "'\"`":
424+
quote = character
425+
start = index
426+
index += 1
427+
while index < len(text):
428+
if text[index] == "\\":
429+
index += 2
430+
continue
431+
if quote == "`" and text.startswith("${", index):
432+
# Interpolated templates need a JavaScript parser to prove
433+
# inert; fail closed rather than hide their expression.
434+
return None
435+
if text[index] == quote:
436+
index += 1
437+
break
438+
index += 1
439+
else:
440+
return None
441+
result.append(text[start:index])
442+
continue
443+
if text.startswith("//", index):
444+
while index < len(text) and text[index] not in "\r\n":
445+
result.append(" ")
446+
index += 1
447+
continue
448+
if text.startswith("/*", index):
449+
end = text.find("*/", index + 2)
450+
if end < 0:
451+
return None
452+
comment = text[index : end + 2]
453+
result.extend(
454+
"\n" if char == "\n" else "\r" if char == "\r" else " " for char in comment
455+
)
456+
index = end + 2
457+
continue
458+
result.append(character)
459+
index += 1
460+
return "".join(result)
461+
462+
463+
def _looks_like_typescript_declaration(path: str, data: bytes, *, complete_content: bool) -> bool:
464+
"""Recognize clearly inert TypeScript declaration content conservatively.
465+
466+
Declaration suffixes alone are not trusted: a file named ``evil.d.cts``
467+
can still contain executable CommonJS. Unknown or non-text content stays
468+
executable so this check cannot create a name-based security bypass.
469+
"""
470+
name = Path(path).name.lower()
471+
if not complete_content or not name.endswith(_TYPESCRIPT_DECLARATION_SUFFIXES) or not data:
472+
return False
473+
try:
474+
text = data.decode("utf-8")
475+
except UnicodeDecodeError:
476+
return False
477+
uncommented = _strip_typescript_comments(text)
478+
return bool(
479+
uncommented and uncommented.strip() and _TYPESCRIPT_DECLARATION_FILE.fullmatch(uncommented)
480+
)
481+
392482

393483
def has_binary_executable_magic(data: bytes) -> bool:
394484
"""Return whether canonical bytes begin with supported executable magic."""
395485
return has_dex_magic(data) or data.startswith(_BINARY_EXECUTABLE_MAGICS)
396486

397487

398-
def is_executable_content(path: str, data: bytes, mode: int = 0) -> bool:
399-
"""Classify filesystem and archive content with one static-only policy."""
488+
def is_executable_content(
489+
path: str, data: bytes, mode: int = 0, *, complete_content: bool = False
490+
) -> bool:
491+
"""Classify content; only complete declarations may receive the inert exemption."""
400492
suffix = Path(path).suffix.lower()
401493
executable_magic = data.startswith(b"#!") or has_binary_executable_magic(data)
402-
return suffix in _EXECUTABLE_SUFFIXES or executable_magic or bool(mode & 0o111)
494+
declaration_only = _looks_like_typescript_declaration(
495+
path, data, complete_content=complete_content
496+
)
497+
return (
498+
(suffix in _EXECUTABLE_SUFFIXES and not declaration_only)
499+
or executable_magic
500+
or bool(mode & 0o111)
501+
)
403502

404503

405504
def _member_executable(info: zipfile.ZipInfo, safe_name: str, data: bytes) -> bool:
406-
return is_executable_content(safe_name, data, info.external_attr >> 16)
505+
return is_executable_content(
506+
safe_name,
507+
data,
508+
info.external_attr >> 16,
509+
complete_content=len(data) == info.file_size,
510+
)
407511

408512

409513
def _nested_path(outer_path: str, virtual_path: str) -> str:

‎src/skillspector/nodes/build_context.py‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -930,7 +930,9 @@ def _expired(path: str) -> bool:
930930
size_bytes = 0
931931
mode = 0
932932
data = raw_file_cache.get(path, b"")
933-
executable = is_executable_content(path, data, mode)
933+
executable = is_executable_content(
934+
path, data, mode, complete_content=len(data) == size_bytes
935+
)
934936
if executable:
935937
has_executable = True
936938
component: dict[str, object] = {
@@ -1355,7 +1357,12 @@ def runtime_exhausted(
13551357
executable=executable,
13561358
)
13571359
continue
1358-
executable = is_executable_content(path, probe, file_stat.st_mode)
1360+
executable = is_executable_content(
1361+
path,
1362+
probe,
1363+
file_stat.st_mode,
1364+
complete_content=len(probe) == size_bytes,
1365+
)
13591366
archive_candidate = is_zip_content(probe)
13601367
expected_archive = expected_container_type(path) is not None
13611368
if expected_archive and not archive_candidate:

‎tests/nodes/test_build_context.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1074,6 +1074,7 @@ def test_build_context_inventories_excluded_executable_descendants(tmp_path: Pat
10741074
"node_modules/pkg/index.js": b"alert(1)\n",
10751075
"node_modules/pkg/module.wasm": b"\x00asm\x01\x00\x00\x00",
10761076
"node_modules/pkg/payload.mjs": b"export default () => 1;\n",
1077+
"node_modules/pkg/evil.d.mts": b'export{}; console.log("runtime payload after the short executable probe");\n',
10771078
"node_modules/pkg/vector.svg": b"<svg><script>alert(1)</script></svg>\n",
10781079
".venv/bin/launcher": b"#!/bin/sh\necho launch\n",
10791080
".tox/env/payload.pyc": b"\x00",
@@ -1089,6 +1090,7 @@ def test_build_context_inventories_excluded_executable_descendants(tmp_path: Pat
10891090
"node_modules/pkg/index.js",
10901091
"node_modules/pkg/module.wasm",
10911092
"node_modules/pkg/payload.mjs",
1093+
"node_modules/pkg/evil.d.mts",
10921094
"node_modules/pkg/vector.svg",
10931095
".venv/bin/launcher",
10941096
".tox/env/payload.pyc",

‎tests/nodes/test_nested_artifacts.py‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,129 @@ def _document_members(**extra: bytes) -> dict[str, bytes]:
6868
}
6969

7070

71+
def test_typescript_declaration_files_are_not_executable_by_name_alone() -> None:
72+
declaration = b"export interface Options { retries?: number; }\nexport type Result = string;\n"
73+
74+
assert not is_executable_content("types.d.cts", declaration, complete_content=True)
75+
assert not is_executable_content("types.d.mts", declaration, complete_content=True)
76+
77+
78+
def test_runtime_code_in_typescript_declaration_named_file_stays_executable() -> None:
79+
runtime = b'declare const marker: string;\nrequire("child_process").execSync(marker);\n'
80+
81+
assert is_executable_content("evil.d.cts", runtime)
82+
83+
84+
def test_declaration_exemption_requires_complete_content() -> None:
85+
declaration = b"export {}"
86+
87+
assert is_executable_content("types.d.mts", declaration)
88+
assert not is_executable_content("types.d.mts", declaration, complete_content=True)
89+
90+
91+
def test_runtime_default_import_named_type_is_not_a_type_only_import() -> None:
92+
runtime = b'import type from "./payload.mjs";\n'
93+
94+
assert is_executable_content("evil.d.mts", runtime, complete_content=True)
95+
96+
97+
def test_typescript_declaration_span_cannot_cross_asi_line_break() -> None:
98+
runtime = b'export type Config = string\nconsole.log("RUNTIME")\n;'
99+
100+
assert is_executable_content("evil.d.cts", runtime, complete_content=True)
101+
102+
103+
@pytest.mark.parametrize(
104+
"runtime",
105+
[
106+
b'type A = "/*";\nconsole.log("RUNTIME");\ntype B = "*/";\n',
107+
b'type A = "//"; console.log("RUNTIME")\ntype B = string;\n',
108+
b'type A = `unterminated;\nconsole.log("RUNTIME");',
109+
],
110+
)
111+
def test_comment_markers_inside_literals_cannot_hide_runtime(runtime: bytes) -> None:
112+
assert is_executable_content("evil.d.ts", runtime, complete_content=True)
113+
114+
115+
def test_typical_typescript_emitted_declaration_file_is_inert() -> None:
116+
declaration = (
117+
b"export interface Options { retries?: number; }\n"
118+
b"export declare function load(options: Options): Promise<void>;\n"
119+
b"export type Result = string;\n"
120+
)
121+
122+
assert not is_executable_content("types.d.ts", declaration, complete_content=True)
123+
124+
125+
def test_typescript_side_effect_import_in_declaration_named_file_stays_executable() -> None:
126+
runtime = b"import './payload.js';\nexport type Result = string;\n"
127+
128+
assert is_executable_content("evil.d.mts", runtime)
129+
130+
131+
def test_mixed_typescript_declaration_and_runtime_stays_executable() -> None:
132+
runtime = b"export type Result = string;\nconsole.log('runtime');\n"
133+
134+
assert is_executable_content("evil.d.ts", runtime)
135+
136+
137+
@pytest.mark.parametrize("path", ["types.d.ts", "types.d.cts", "types.d.mts"])
138+
def test_ambient_typescript_namespaces_and_modules_are_declarations(path: str) -> None:
139+
declaration = (
140+
b"declare namespace Payload { interface Value { name: string; } }\n"
141+
b'declare module "payload" { export function load(): string; }\n'
142+
)
143+
144+
assert not is_executable_content(path, declaration, complete_content=True)
145+
146+
147+
@pytest.mark.parametrize(
148+
"runtime",
149+
[
150+
b'namespace Payload { console.log("runtime"); }\n',
151+
b'export namespace Payload { console.log("runtime"); }\n',
152+
b'declare namespace Payload { console.log("runtime"); }\n',
153+
],
154+
)
155+
def test_typescript_namespace_bodies_must_be_proven_ambient(runtime: bytes) -> None:
156+
assert is_executable_content("evil.d.ts", runtime)
157+
158+
159+
@pytest.mark.parametrize(
160+
"runtime",
161+
[
162+
b'type = console.log("runtime");\n',
163+
b"namespace: { console.log('runtime'); }\n",
164+
],
165+
)
166+
def test_ambiguous_typescript_keywords_stay_executable(runtime: bytes) -> None:
167+
"""Assignments and labels must not be mistaken for declarations."""
168+
assert is_executable_content("evil.d.mts", runtime)
169+
170+
171+
@pytest.mark.parametrize(
172+
"runtime",
173+
[
174+
b'type = console.log("runtime");\n',
175+
b"namespace: { console.log('runtime'); }\n",
176+
],
177+
)
178+
def test_ambiguous_typescript_keywords_in_hidden_documents_raise_sc9(
179+
tmp_path: Path, runtime: bytes
180+
) -> None:
181+
archive_path = tmp_path / ".types.docx.txt"
182+
_write_archive(archive_path, _document_members(**{"word/payload.d.mts": runtime}))
183+
(tmp_path / "SKILL.md").write_text("# Declaration container\n", encoding="utf-8")
184+
185+
context = build_context({"skill_path": str(tmp_path)})
186+
virtual_path = ".types.docx.txt!/word/payload.d.mts"
187+
metadata = next(item for item in context["component_metadata"] if item["path"] == virtual_path)
188+
assert metadata["executable"] is True
189+
assert metadata["concealed_executable"] is True
190+
findings = _analyze_concealed_executables(context["component_metadata"])
191+
assert any(finding.rule_id == "SC9" and finding.file == virtual_path for finding in findings)
192+
193+
71194
@pytest.mark.parametrize(
72195
("path", "payload"),
73196
[

0 commit comments

Comments
 (0)