Skip to content

feat(frontends): Jupyter notebook support (.ipynb) - #16

Closed
Sagexd08 wants to merge 2 commits into
arpankernel:mainfrom
Sagexd08:feat/notebook-support
Closed

Sagexd08 wants to merge 2 commits into
arpankernel:mainfrom
Sagexd08:feat/notebook-support

Conversation

@Sagexd08

Copy link
Copy Markdown

What

A new frontend for .ipynb files. Notebook code lives in cells with no engine-level concept of "cell" - and a notebook is one execution unit: a name bound in cell 1 is used in cell 3, exactly like top-level statements in a .py file. So NotebookFrontend reassembles a notebook's code cells into one Python source and delegates entirely to PythonFrontend, rather than parsing cells in isolation (which would either miss that cross-cell data flow or require reinventing scope resolution the engine has no seam for).

Zero engine changes - every existing rule, the taint engine, and PI-AGENT-HANDOFF all work on notebooks for free, matching the project's own precedent for a new frontend (the JS/TS tree-sitter frontend landed the same way).

How

  • src/palisade_sec/frontends/notebook.py: parses .ipynb JSON (never imports/execs/evals notebook content or metadata), reassembles code cells nbconvert-style (a # In[N]: marker line per cell, so a reported line number is traceable back to a cell by counting markers), blanks IPython line/cell magics (%matplotlib inline, !pip install, %%time) since they aren't Python and ast.parse would reject them outright, and skips a non-Python-kernel notebook (metadata.language_info.name) with a clear reason instead of guessing at another language's IR.
  • scanner.py: registers .ipynb via the same Frontend protocol every other frontend uses (NB_EXTENSIONS, _make_frontends, collect_files's extension filter); .ipynb_checkpoints/ joins the always-excluded directory list.
  • Resilience: malformed JSON, non-dict/missing-cells shapes, and pathologically nested JSON (json.loads raises RecursionError the same way ast.parse does on deeply nested Python) are all caught the same way as any other frontend's ParseFailure - skipped with a warning, never a crash. New hostile fixture (deep_nested.ipynb, 5000-deep nested array) added to the self-security corpus alongside the existing deep_parens.py/huge.py/etc.
  • Docs: docs/architecture.md + docs/getting-started.md (and their docs-site mirrors) updated to mention the notebook frontend.

Testing

tests/test_notebook_frontend.py (12 tests) mirrors test_js_frontend.py's role:

  • End to end through run_scan: a prompt-injection path split across two code cells (with a markdown cell and a %matplotlib inline magic in between) is correctly flagged; a safe notebook and a markdown-only notebook stay silent.
  • Resilience: invalid JSON, JSON that isn't an object, missing cells, and a cell body that isn't valid Python are all skipped with a clear reason, never a crash.
  • A non-Python-kernel (R) notebook is skipped with a clear reason.
  • reassemble() unit tests independent of ast.parse.

Manually verified end to end against real .ipynb fixtures beyond the automated tests (a realistic vulnerable notebook, a safe one, a malformed one, a non-Python-kernel one) - see the commit message for exact scan --json output.

Verified: 311 passed / 1 skipped, ruff/mypy clean on touched files, precision=1.000 recall=1.000 on the fixture corpus, example-app pin holds, self-scan (scan src --ci) exits 0. The 4 test failures present without this branch's changes (2 in test_demo_script.py, 2 in test_cli_hardening.py/test_output_safety.py from Windows-reserved characters in a fixture filename) are pre-existing on a clean upstream/main checkout on this machine, confirmed via a separate worktree - not introduced here.

Note

This branch was rebased onto upstream/main after the 0.5.1 hardening release landed underneath it; no conflicts in the actual code (only a CHANGELOG.md section-ordering conflict), since notebook support doesn't touch the sanitizer/engine code that release changed.

Copilot AI lite review requested due to automatic review settings September 22, 2026 11:00

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@arpankernel

Copy link
Copy Markdown
Owner

This is the best-engineered of your four, and it's a real gap — there is no notebook support in src/ at all, and notebooks are a named Phase 2 item in docs/roadmap.md. I want it.

What I checked: it merges clean onto main (only CHANGELOG.md conflicts), the suite passes, and a vulnerable 3-cell notebook goes from files_scanned: 0 on main to PI-EXEC high vuln.ipynb:12 with your branch. Zero new dependencies, stdlib json only, and the module never executes notebook content. Your cross-cell dataflow test — setup in cell 1, sink in cell 3 — is the right test to have written, because that's the case per-cell parsing would miss.

Two things to fix before I merge, both found by testing rather than by reading:

1. Inline suppressions are silently inert in notebooks. src/palisade_sec/scanner.py:304 calls parse_suppressions(source) on the raw file text — which for a .ipynb is the JSON, not your reassembled source. So exec(code) # palisade: ignore[PI-EXEC] - reviewed, sandboxed inside a cell does nothing: the finding still fires, suppressed: 0. The same comment in a .py suppresses correctly.

That matters more than it looks. The roadmap's line is "a silent suppression is how a vulnerability quietly returns" — and a silently inert suppression breaks the same contract from the other side: a user marks a false positive reviewed, nothing happens, and they have no way to tell why. Needs a seam so parse_suppressions sees the reassembled text. Please add a must-suppress test and a stale-suppression test.

2. Line numbers break SARIF / GitHub code scanning. Findings carry reassembled-source line numbers against the .ipynb path. For a single-line-JSON notebook, SARIF emits region.startLine: 12 for a file with one line. For a pretty-printed notebook line 12 exists but lands on arbitrary JSON metadata — a confidently wrong annotation, which is worse than none.

I don't have a strong preference on the fix: suppress region info for .ipynb, or map back to a real JSON line. Either is fine, but it needs a decision and a SARIF assertion test for a notebook finding. Your docstring documents the convention, which is good — it just doesn't reach the SARIF consumer.

Then a rebase on current main and a CHANGELOG.md entry under the current heading, and I'll merge. Worth also noting the "line numbers are reassembled-source lines" convention in docs/cli-reference.md, where the --json schema contract lives, since it affects a stable interface.

Thanks for the hostile fixture, by the way — I checked it skips cleanly rather than crashing.

Sagexd08 and others added 2 commits October 1, 2026 16:13
Notebook code lives in cells with no engine-level concept of "cell" - and a
notebook is one execution unit: a name bound in cell 1 is used in cell 3,
exactly like top-level statements in a .py file. So the frontend reassembles
a notebook's code cells into one Python source and delegates entirely to
PythonFrontend, rather than parsing cells in isolation (which would either
miss that cross-cell data flow or require reinventing scope resolution the
engine has no seam for). Zero engine changes - every existing rule, the
taint engine, and PI-AGENT-HANDOFF all work on notebooks for free, matching
the project's own "new language: zero engine changes expected" contract for
the JS/TS frontend.

- src/palisade_sec/frontends/notebook.py: parses .ipynb JSON (never
  imports/execs/evals notebook content or metadata - SF-1), reassembles code
  cells nbconvert-style (a `# In[N]:` marker line per cell, so a reported
  line number is traceable back to a cell by counting markers), blanks
  IPython line/cell magics (%matplotlib, !pip install, %%time) since they
  are not Python and ast.parse would reject them outright, and skips a
  non-Python-kernel notebook (metadata.language_info.name) with a clear
  reason instead of guessing at another language's IR.
- scanner.py: registers .ipynb via the same Frontend protocol every other
  frontend uses (NB_EXTENSIONS, _make_frontends, collect_files' extension
  filter); .ipynb_checkpoints/ joins the always-excluded directories.
- Resilience: malformed JSON, non-dict/missing-cells shapes, and
  pathologically nested JSON (json.loads raises RecursionError the same way
  ast.parse does on deeply nested Python) are all caught the same way as any
  other frontend's ParseFailure - skipped with a warning, never a crash
  (RB-3). New hostile fixture (deep_nested.ipynb) added to the self-security
  corpus alongside the existing deep_parens.py/huge.py/etc.

Docs: docs/architecture.md + docs/getting-started.md (and their docs-site
mirrors) updated to mention the notebook frontend, per AGENTS.md's doc-sync
requirement.

Verified: 254 passed / 1 skipped (was 242 on main baseline before this
branch), ruff/mypy clean on touched files, precision=1.000 recall=1.000 on
the fixture corpus, example-app pin holds, self-scan (`scan src --ci`)
exits 0. Manually verified end to end against real .ipynb fixtures: a
prompt-injection path split across two cells (with a %matplotlib magic in
between) is correctly flagged; a safe notebook, a markdown-only notebook, a
malformed-JSON notebook, and a non-Python-kernel (R) notebook all correctly
stay silent / skip cleanly.

Note: test_self_security.py's hostile-corpus test has a known, pre-existing
or-dependent flake (audit hook matches co_filename == "<string>", which the
stdlib's collections.namedtuple triggers via tomllib) when run in isolation
or certain subsets - present on a clean upstream/main checkout too, not
introduced here. Passes reliably as part of the full suite.
Both issues from the review on arpankernel#16, both found by
testing rather than reading, plus the rebase and CHANGELOG entry it asked
for.

1. Inline suppressions were silently inert in notebooks.

`lower_project` called `parse_suppressions(source)` on the raw file text,
which for a `.ipynb` is JSON, not the reassembled cell source a finding's
line number refers to. So an in-cell

    exec(code)  # palisade: ignore[PI-EXEC] - reviewed, sandboxed

did nothing: the finding still fired and `suppressed_inline` stayed 0,
while the same comment in a `.py` suppressed correctly.

Worse than inert, in fact. The comment was still parsed - against JSON
line numbers - so it could match a finding whose reassembled line
happened to collide with the JSON line holding that cell's source string,
silencing something the user never marked. Both halves are the failure
invariant 10 exists to prevent: a user marks a false positive reviewed
and gets neither a suppression nor a stale-suppression warning telling
them why, or gets a suppression they did not ask for.

The seam is a second `Frontend` Protocol method, `suppression_source`:
the scanner reads suppressions from the text the frontend actually
parsed. Python and JS/TS return the source unchanged; the notebook
frontend returns the reassembled cells. It is on the Protocol rather than
duck-typed so a future frontend that rewrites source and forgets it fails
mypy at the `dict[str, Frontend]` assignment - verified by removing the
method and watching mypy name it - instead of shipping inert
suppressions.

2. Notebook line numbers broke SARIF / GitHub code scanning.

A `.ipynb` finding carried a reassembled-source line as
`region.startLine` against the notebook's path. For a single-line
notebook that line does not exist; for a pretty-printed one it lands on
arbitrary JSON metadata. A confidently wrong annotation is worse than
none.

Decision: anchor a notebook result at the file (`startLine: 1`) and carry
the real line in the result message and in
`properties["palisade/notebookSinkLine"]`, with the per-location role
messages carrying the short form. The region is kept rather than omitted
deliberately: GitHub code scanning requires `region.startLine` and
rejects the whole run without it, so one region-less result would discard
every finding in the upload - which is why "suppress region info" is not
literally what landed. `region.snippet` still carries the real sink text,
so the alert names the code even though it cannot point at it. Findings
in ordinary files keep their real line, pinned by a test.

Tests (9 new, 21 in the file):

- must-suppress, on the sink line and on the line above
- must-stale: a notebook comment matching nothing is reported at its
  reassembled-source line (`stale.ipynb:2`)
- must-NOT-suppress: `# palisade: ignore[...]` in markdown prose cannot
  silence anything
- the unsuppressed control, so the three above cannot pass vacuously
- `suppression_source` is the reassembled text, and is empty rather than
  raising on an unreadable notebook
- SARIF: notebook result and related locations at `startLine: 1`, real
  line in the message and properties
- SARIF: a `.py` finding keeps its real line and gains no notebook
  properties - the carve-out must not leak

Docs: the "line numbers are reassembled-source lines" convention is now
in `docs/cli-reference.md` under the `--json` schema contract (with the
two ways to resolve one back to a cell), in the SARIF section, and in the
inline-suppressions section; the `Frontend` seam is in
`docs/architecture.md`. Both docs-site mirrors updated. `schema_version`
stays 1: the `--json` `line` field is unchanged and now documented, not
redefined.

Rebased onto main at be6dfbc (0.7.0); the only conflict was CHANGELOG
section ordering, resolved by placing the notebook entry under a new
`## Unreleased` heading above 0.7.0.

Gates: 556 passed / 2 skipped, ruff + mypy clean, precision=1.000
recall=1.000 on the fixture corpus, example-app pin holds (4 high + 1 med
in 6 files) and still exits 1 under --ci, self-scan `scan src --ci` exits
0, self-security suite green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ML1AaDDCDkX6fv4NUAmV6
@Sagexd08
Sagexd08 force-pushed the feat/notebook-support branch from 75dbc9d to bef2550 Compare October 1, 2026 16:22
@Sagexd08 Sagexd08 closed this Oct 3, 2026
@Sagexd08 Sagexd08 reopened this Oct 3, 2026
@Sagexd08 Sagexd08 closed this Oct 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants