Skip to main content

No project description provided

Project description

Twyn

Build Status PyPI version Python Version Code style License

Twyn is a security tool that compares the name of your dependencies against a set of the most popular ones, in order to determine if there is any similarity between them, preventing you from using a potentially illegitimate one. In short, Twyn protects you against typosquatting attacks.

It works as follows:

  1. Either choose to scan the dependencies in a dependencies file you specify (--dependency-file) or some dependencies introduced through the CLI (--dependency). If no option was provided, it will try to find a dependencies file in your working path.
  2. If the name of your package name matches with the name of one of the most well known packages, the package is accepted.
  3. If the name of your package is similar to the name of one of the most used packages, Twyn will prompt an error.
  4. If your package name is not in the list of the most known ones and is not similar enough to any of those to be considered misspelled, the package is accepted. Twyn assumes that you're using either a not so popular package (therefore it can't verify its legitimacy) or a package created by yourself, therefore unknown for the rest.

Quickstart

Installation

Twyn is available on PyPi repository, you can install it by running

pip install twyn

Docker

Twyn provides a Docker image, which can be found here.

Use it like so:

docker pull elementsinteractive/twyn:latest
docker run elementsinteractive/twyn --help

Run

To run twyn simply type:

twyn run <OPTIONS>

For a list of all the available options as well as their expected arguments run:

twyn run --help

Configuration

Allowlist

It can happen that a legitimate package known by the user raises an error because is too similar to one of the most trusted ones. You can then add this packages to the allowlist, so it will be skipped:

twyn allowlist add <package>

To remove it simply:

twyn allowlist remove <package>

Dependency files

To specify a dependency file through the command line run:

twyn run --dependency-file <file path>

Currently it supports these dependency file formats:

  • requirements.txt
  • poetry.lock

Check dependencies introduced through the CLI

You can also check a dependency by entering it through the command line:

twyn run --dependency <dependency>

It does accept multiple dependencies at a time:

twyn run --dependency <dependency> --dependency <another_dependency>

When this option is selected, no dependency file is checked.

Selector method

You can choose between different operational modes. These will determine which dependencies from the trusted set the analyzed dependency can be a typosquat of.

  • all: Default option. It is the most exhaustive mode. It will check your package names against all the trusted ones without any assumption.
  • nearby-letter: It will assume a typo on the first letter of the dependency is possible, but improbable if letters are farther apart in the keyboard. Specifically, it will compare the analyzed dependency against dependencies whose first letter is one step away in an ANSI keyboard layout.
  • first-letter: It will assume a typo on the first letter is very improbable, and won't compare the analyzed dependency against dependencies with a different first letter.

[!NOTE] Selecting an option is a matter of preference: all is the slowest, but will have more false positives and less false negatives; while first-letter is the fastest, but it will have less false positives and more false negatives.

To select a specific operational mode through the CLI use the following command

twyn run --selector-method <method>

Configuration file

You can save your configurations in a .toml file, so you don't need to specify them everytime you run Twyn in your terminal.

By default, it will try to find a pyproject.toml file in your working directory when it's trying to load your configurations. However, you can specify a config file as follows:

twyn run --config <file>

All the configurations available through the command line are also supported in the config file.

[tool.twyn]
dependency_file="/my/path/requirements.txt"
selector_method="first_letter"
logging_level="debug"
allowlist=["my_package"]
pypi_reference="https://mirror-with-trusted-dependencies.com/file.json"

[!WARNING] twyn will have a default reference URL for every source of trusted packages that is configurable. If you want to protect yourself against spoofing attacks, it is recommended to set your own reference url.

The file format for each reference is as follows:

  • PyPI reference:
{
    rows: {project: string}[]
}

Project details


Release history Release notifications | RSS feed

Download files

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

Source Distribution

twyn-2.8.1.tar.gz (16.3 kB view details)

Uploaded Source

Built Distribution

twyn-2.8.1-py3-none-any.whl (20.6 kB view details)

Uploaded Python 3

File details

Details for the file twyn-2.8.1.tar.gz.

File metadata

  • Download URL: twyn-2.8.1.tar.gz
  • Upload date:
  • Size: 16.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.4 CPython/3.10.2 Linux/6.5.0-1025-azure

File hashes

Hashes for twyn-2.8.1.tar.gz
Algorithm Hash digest
SHA256 8cf651f9b7d171a0042b76b7b4cd05156dab939a4042f0f558dd2aa22eded42f
MD5 0af8ba9cf02b01308a957db941321a9b
BLAKE2b-256 82ad7335e7cb0836c0731bfa1b121bf6fafafb460f850bba22aefa9091586eb7

See more details on using hashes here.

File details

Details for the file twyn-2.8.1-py3-none-any.whl.

File metadata

  • Download URL: twyn-2.8.1-py3-none-any.whl
  • Upload date:
  • Size: 20.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.4 CPython/3.10.2 Linux/6.5.0-1025-azure

File hashes

Hashes for twyn-2.8.1-py3-none-any.whl
Algorithm Hash digest
SHA256 2a013745459f0f6c28406a37e10fa55767fc8dd3b6b7fa0d6ebc35eca19777bd
MD5 622d5841f61bfaa2fc84d6858ab2869f
BLAKE2b-256 d9902637c4332e083af34ca4546e9c99668cfc13afbec08e430fd670ecb8ab10

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page