Skip to content

About

Jupyter GitHub inventory tools for public security purposes

Topics

Resources

Code of conduct

Security policy

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

Jupyter Security Inventory

Project Jupyter has over 400 public repositories across 20 GitHub organizations. This project collects, for each repository, some data like how many people install it, how many other Jupyter repositories run its code in CI, whether it runs a live service, and whether it's a security boundary.

Eventual goals

  • Expose a "todo list" of bite-sized security improvements from which contributors can pick from.
  • Be a tool to prioritize where security time is spent first using metrics
  • And eventually aggregate more data (like trusted publishing) in an effort to centralize what we do manually in https://github.com/jupyter/security/issues.

Structure

  • In output/: the results of the scripts described below. Do not write here.
  • In docs/: a sphinx website that makes the results browsable.

How it works

Eight scripts run in order (they depend on each other):

Step What it does Data from
1. Inventory Lists the public, non-archived repositories of each organization GitHub
2. Scan Clones each repository and reads its workflows, actions, package manifests, chartpress files, pre-commit config, README and SECURITY.md GitHub
3. Packages Matches PyPI and npm packages to repositories, with downloads, dependents, the date of the last release, how the latest release was published and the Python versions it allows PyPI, npm, pypistats.org, deps.dev
4. Images Lists the images published on Docker Hub and Quay and matches them to repositories. Also writes output/images.txt, one image per line Docker Hub, Quay
5. Labels Decides each repository's kind, the live service it deploys and whether it's a security boundary, and why LLM
6. Merge Puts it all together and works out which repositories run each other's code
7. Table Writes output/repos.csv
8. Topics Answers each security topic for every repository and counts the answers each day

architecture.md explains how the pieces fit together.

The columns

  • kind: package, application, tooling, deployment, documentation, example or other.
  • owner: its Owner custom property on GitHub.
  • downloads/month and dependents: for the repository's most downloaded package.
  • image and all-time pulls: for the repository's most pulled container image.
  • used in CI: how many other Jupyter repositories run its actions or build tools without pinning them to a commit.
  • live service: the site or service it deploys, like mybinder.org.
  • security boundary: whether its bugs can be exploited over the network, because it handles logins, proxies traffic, runs multi-user servers or runs code and content from the network, and why.

Security topics

A topic asks one question about every repository, like "does it check its workflows with zizmor?", and answers with a status: done, partial, missing or not applicable. Each topic has a page, and every organization and repository page shows how it does. The topics for now:

  • zizmor, run as its GitHub Action, as a command in a workflow or as a pre-commit hook.
  • SECURITY.md, in the repository or in the organization's .github repository, for the repositories that ship a package or an image.
  • PyPI attestations, on every file of the latest release of each PyPI package. PyPI's API shows trusted publishing only through attestations, so it has no topic of its own.
  • npm trusted publishing, for the latest version of each npm package.
  • Supported Python: the Requires-Python of the latest release of each PyPI package leaves out the Python versions that no longer get security fixes.
  • Owner: the repository's Owner custom property is set, and not "None".

Caveats

  • Repository type, and security boundary come from a language model
  • Download counts include CI.
  • A package is found only through a repository of this inventory.
  • Images: ghcr.io is not covered, Quay has no pull counts, and one tag is recorded per image: latest, or the newest. The namespaces are listed by hand in scripts/4_images.py. Many older images match no repository.
  • "Used in CI" only sees the repositories listed here.
  • The zizmor and SECURITY.md topics read the repository's files, so they show what is set up, not what is enforced. pre-commit.ci can't be seen from the files, so a pre-commit hook counts as run by CI only if a workflow runs pre-commit or the config has a ci: section.

Running it

You need Python >= 3.14, the GitHub CLI (logged in), and a DeepSeek API key for step 5 (or an OpenAI key, with --model <an OpenAI model>).

pip install . --group dev --group docs
python scripts/1_inventory.py
python scripts/2_scan_repos.py --clone-dir ~/clones
python scripts/3_packages.py
python scripts/4_images.py
python scripts/5_classify.py --clone-dir ~/clones
python scripts/6_build_dataset.py
python scripts/7_table.py
python scripts/8_topics.py

Then build the site with sphinx-build -W docs docs/_build, and open docs/_build/index.html.

With pixi

pixi installs Python 3.14, the GitHub CLI and the same dependencies, and runs each step as a task. pixi task list shows them all, with the steps first, in order.

pixi run pipeline        # steps 1 to 8
pixi run 2-scan ~/clones # one step; the clone directory is ~/clones by default
pixi run outputs         # steps 6 to 8
pixi run test
pixi run lint
pixi run docs            # build the site into docs/_build
pixi run docs-watch      # serve the site at http://127.0.0.1:8000 and rebuild on changes

Read the Docs builds the site the same way, with .readthedocs.yaml.

Daily updates

A GitHub Actions workflow (update.yml) reruns the whole pipeline every morning, commits what changed in output/, and Read the Docs rebuilds the site. It needs a DEEPSEEK_API_KEY repository secret.

Step 5 only labels repositories it hasn't labeled yet with the current model, so a daily run costs almost nothing. To relabel everything, switch to another model or delete output/classification.json.

Contributing

Change the scripts, never output/ by hand. Rerun the pipeline from the step you changed, run pytest, and commit the new outputs with your change. CI runs the tests and checks that the outputs of steps 6 to 8 are up to date.

The daily update installs requirements.txt, which pins every dependency, including indirect ones, to an exact version. Read the Docs installs pixi.lock. After changing the dependencies in pyproject.toml, regenerate requirements.txt with the command on its second line, and pixi.lock with pixi lock.

License

BSD 3-Clause.

About

Jupyter GitHub inventory tools for public security purposes

Topics

Resources

Code of conduct

Security policy

Stars

0 stars

Watchers

1 watching

Forks

Contributors

Languages