Skip to main content

Software Heritage - Code Scanner

Source code scanner to analyze code bases and compare them with source code artifacts archived by Software Heritage.

Bibliography

In addition to accompanying technical documentation, swh-scanner is also described in the following scientific paper. If you use swh-scanner for your research work, please acknowledge it by citing:

Getting Started

Installation

To install the Software Heritage scanner, run:

pip install swh-scanner

Note that it will install swh-scanner and its dependencies in the current virtualenv (if any). If you just want to install the scanner as a standalone tool, you may want to use an installation tool like pipx or uv:

$ uv tool install --with swh-scanner swh-core

or

$ pipx install --include-deps swh-scanner

Registering to the Software Heritage Archive

To efficiently query the Software Heritage Archive, you need to create an account. This is not strictly necessary, but the rate limit imposed on anonymous users will likely result in very slow operation.

First, visit https://archive.softwareheritage.org/oidc/login/ and create a new user by clicking on Register.

Configuring your scan

The scanner will guide you through your initial configuration through the setup command, including setting up your authentication token:

swh scanner setup

Running a Scan

To scan your local file in PROJECT_PATH, use:

swh scanner scan PROJECT_PATH

This will find your local files, query the archive, and provide you with a graphical user interface to browse the result.

Note that the scan command has a --provenance flag that retrieves information about where the files known to the archive might come from. This option is experimental and you need to get in touch with the Software Heritage team to be granted permission to the necessary APIs. Alternatively, there is a button in the dashboard that will query the provenance for a given selected file or directory. This is also experimental and gated to privileged users.

Further Configuration

The scanner will add up configuration options from three places, in order of precedence:

  • The command line

  • The project config file

  • The global config file

You can view the command line options by invoking swh scanner scan --help.

The scanner will look for a swh.scanner.project.yml file inside the directory being scanned, or at the path given to --project-config-file.

The global configuration resides in the swh > scanner section of the shared YAML configuration file used by all Software Heritage tools, located by default at ~/.config/swh/global.yml.

The configuration file location is subject to the XDG Base Directory specification as well as explicitly overridden on the command line via the -C/--config-file flag.

The following sub-sections and fields can be used within the swh > scanner stanza:

  • disable_global_patterns (default: false): whether to disable the global exclusion patterns, which refer to very common patterns of files to exclude from the scan. Only use this if you’re finding that some files are being ignored that you would want to scan, though very unlikely.

  • disable_vcs_patterns (default: false): whether to stop using the ignore mechanisms from version control systems (.gitignore, .hgignore, .svnignore). Note that this ignore mechanism only works in the first place if the VCS is available in your PATH (Git, Mercurial or SVN).

  • exclude: (default: []): a list of glob patterns of paths to exclude from the scan, to use on top of all other exclusion patterns.

  • exclude_templates: (default: []): a list of names of exclusion templates (as listed in the scanner’s help) to use on top of all other exclusion patterns. This is useful if you want to exclude all common Python cache files for example.

Here is an example:

scanner:
  disable_global_patterns: false
  disable_vcs_patterns: false
  exclude: ["ignored*", "someotherpattern"]
  exclude_templates: ["Python", "Go", "Rust", "Node"]

Metadata

Release files for swh.scanner 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for swh.scanner 0.9.0
File Size Uploaded Provenance Actions
swh_scanner-0.9.0.tar.gz 192.5 kB Without provenance Details for swh_scanner-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for swh.scanner 0.9.0
File Interpreter ABI Platform Actions
swh_scanner-0.9.0-py3-none-any.whl Python 3 none any Details for swh_scanner-0.9.0-py3-none-any.whl

Total release size: 454.4 kB

Release files / swh_scanner-0.9.0.tar.gz

Download URL swh_scanner-0.9.0.tar.gz
Size 192.5 kB
Tags Source
SHA-256 checksum
How to use checksums
c317dcd867fb75ea21fee1b57c4280e854b1bef5dfc7c20a8e644ca6115717fe
BLAKE2b-256 checksum
How to use checksums
984676babf5fe4e3b48f1508313fd7edac2dfc28b07f86f1e99b25cd02c8958b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.15

Release files / swh_scanner-0.9.0-py3-none-any.whl

Download URL swh_scanner-0.9.0-py3-none-any.whl
Size 261.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2dc2504f8ca76d089b4d02122040a9763c93779b502cdbeea0ecc24f84b7a1e7
BLAKE2b-256 checksum
How to use checksums
542e7c2cb192e2bd5323fb9b276bf73f79407c6af27aead609497956c4acc172
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.15

Security for swh.scanner 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page