Skip to main content

Security audit Python project dependencies against security advisory databases.

Project description

        .         .    .      Skjold /skjɔl/
    ,-. | , . ,-. |  ,-|
    `-. |<  | | | |  | |      Security audit python project dependencies
    `-' ' ` | `-' `' `-´      against several security advisory databases.


It currently supports fetching advisories from the following sources:

Unless configured explicitly skjold will run the given packages against all of them. There is (currently) no de-duplication meaning that using all of them could result in a lot of duplicates. Source can be added disabled by setting sources list (see Configuration).


Skjold was initially created for myself to replace safety. Which appears to no longer receive monthly updates (see pyupio/safety-db #2282). I wanted something I can run locally and use for my local or private projects/scripts.

I currently also use it during CI builds and before deploying/publishing containers or packages.


skjold can be installed from either PyPI or directly from Github using pip:

pip install git+  # Install from Github
pip install skjold                                        # Install from PyPI

This should provide a script named skjold that can then be invoked. See Usage.


$ pip freeze | skjold -v audit --source gemnasium -

When running audit one can either provide a path to a frozen requirements.txt, a poetry.lock or a Pipfile.lock file. Alternatively, dependencies can also be passed in via stdin (formatted as package==version).

skjold will maintain a local cache (under cache_dir) that will expire automatically after cache_expires has passed. The cache_dir and cache_expires can be adjusted by setting them in tools.skjold section of the projects pyproject.toml (see Configuration for more details). The cache_dirwill be created automatically, and by default unless otherwise specified will be located under $HOME/.skjold/cache.

For further options please read skjold --help and/or skjold audit --help.


All examples involving github assume that SKJOLD_GITHUB_API_TOKEN is already set (see Github).

# Using pip freeze. Checking against GitHub only.
$ pip freeze | skjold audit -s github -

# Be verbose. Read directly from supported formats.
$ skjold -v audit requirements.txt
$ skjold -v audit poetry.lock
$ skjold -v audit Pipenv.lock

# Using poetry.
$ poetry export -f requirements.txt | skjold audit -s github -s gemnasium -s pyup -

# Using poetry, format output as json and pass it on to jq for additional filtering.
$ poetry export -f requirements.txt | skjold audit -o json -s github - | jq '.[0]'

# Using Pipenv, checking against Github
$ pipenv run pip freeze | skjold audit -s github -

# Checking a single package via stdin against Github and format findings as json.
echo "urllib3==1.23" | skjold audit -o json -r -s github -
    "severity": "HIGH",
    "name": "urllib3",
    "version": "1.23",
    "versions": "<1.24.2",
    "source": "github",
    "summary": "High severity vulnerability that affects urllib3",
    "references": [
    "url": ""


skjold can read its configuration from the tools.skjold section of a projects pyproject.toml. Arguments specified via the command-line should take precedence over any configured or default value.

sources = ["github", "pyup", "gemnasium"]  # Sources to check against.
report-only = true                         # Report only, always exit with zero.
report-format = 'json'                     # Output findings as `json`. Default is 'cli'.
cache_dir = '.skylt_cache'                 # Cache location (default: `~/.skjold/cache`).
cache_expires = 86400                      # Cache max. age.
verbose = true                             # Be verbose.

To take a look at the current configuration / defaults run:

$ skjold config
sources: ['pyup', 'github', 'gemnasium']
report_only: True
report_format: json
verbose: False
cache_dir: .skjold_cache
cache_expires: 86400


For the github source to work you'll need to provide a Github API Token via an ENV variable named SKJOLD_GITHUB_API_TOKEN. You can create a new Github Access Token here. You do not have to give it any permissions as it is only required to query the GitHub GraphQL API v4 API.

Version Control Integration

To use skjold with the excellent pre-commit framework add the following to the projects .pre-commit-config.yaml after installation.

  - repo:
    rev: vX.X.X
    - id: skjold
      name: "skjold: Auditing dependencies for known vulnerabilities."
      entry: skjold audit
      language: python
      language_version: python3
      files: ^(poetry\.lock|Pipfile\.lock|requirements.*\.txt)$

After running pre-commit install the hook should be good to go. To configure skjold in this scenario I recommend to add the entire configuration to the projects pyproject.toml instead of manipulating the hook args. See this projects pyproject.toml for an example.


Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for skjold, version 0.1.3
Filename, size File type Python version Upload date Hashes
Filename, size skjold-0.1.3-py3-none-any.whl (16.2 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size skjold-0.1.3.tar.gz (15.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page