https://github.com/elementsinteractive/twyn
Security tool against dependency typosquatting attacks
https://github.com/elementsinteractive/twyn
pipeline python security security-tools typosquatting
Last synced: about 1 month ago
JSON representation
Security tool against dependency typosquatting attacks
- Host: GitHub
- URL: https://github.com/elementsinteractive/twyn
- Owner: elementsinteractive
- License: mit
- Created: 2023-05-05T10:14:13.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2026-04-06T15:20:56.000Z (about 1 month ago)
- Last Synced: 2026-04-06T17:22:28.643Z (about 1 month ago)
- Topics: pipeline, python, security, security-tools, typosquatting
- Language: Python
- Homepage: https://www.elements.nl/en
- Size: 6.63 MB
- Stars: 55
- Watchers: 3
- Forks: 5
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# Twyn
[](https://pypi.org/project/twyn/)
[](https://hub.docker.com/r/elementsinteractive/twyn)
[](https://pypi.org/project/twyn/)
[](https://github.com/astral-sh/ruff)
[](LICENSE)
## Table of Contents
- [Overview](#overview)
- [Quickstart](#quickstart)
- [Using `Twyn` as a cli tool](#using-twyn-as-a-cli-tool)
- [Installation](#installation)
- [Docker](#docker)
- [CLI Options Reference](#cli-options-reference)
- [Run](#run)
- [JSON Format](#json-format)
- [Using `Twyn` as a library](#using-twyn-as-a-library)
- [Logging level](#logging-level)
- [Configuration](#configuration)
- [Allowlist](#allowlist)
- [Dependency files](#dependency-files)
- [Check dependencies introduced through the CLI](#check-dependencies-introduced-through-the-cli)
- [Selector method](#selector-method)
- [Configuration file](#configuration-file)
- [Cache](#cache)
## Overview
`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](https://en.wikipedia.org/wiki/Typosquatting).
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. It will try to parse all the supported dependency files that it finds. To know which files are supported head to the [Dependency files](#dependency-files) section.
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
### Using twyn as a CLI tool
#### Installation
`Twyn` is available on PyPi repository, you can install it by running
```sh
pip install twyn[cli]
```
#### Docker
`Twyn` provides a Docker image, which can be found [here](https://hub.docker.com/r/elementsinteractive/twyn).
Use it like so:
```sh
docker pull elementsinteractive/twyn:latest
docker run elementsinteractive/twyn --help
```
##### CLI Options Reference
| Option / Argument | Type / Values | Description |
|--------------------------|----------------------------------------------------|-----------------------------------------------------------------------------------------------|
| `--config` | `str` (path) | Path to configuration file (`twyn.toml` or `pyproject.toml` by default). |
| `--dependency-file` | `str` (path) | Dependency file to analyze. Supported: `requirements.txt`, `poetry.lock`, `uv.lock`, etc. |
| `--dependency` | `str` (multiple allowed) | Dependency to analyze directly. Can be specified multiple times. |
| `--selector-method` | `all`, `first-letter`, `nearby-letter` | Method for selecting possible typosquats. |
| `--package-ecosystem` | `pypi`, `npm`, `dockerhub` | Package ecosystem for analysis. |
| `-v` | flag | Enable info-level logging. |
| `-vv` | flag | Enable debug-level logging. |
| `--no-cache` | flag | Disable use of trusted packages cache. Always fetch from the source. |
| `--no-track` | flag | Do not show the progress bar while processing packages. |
| `--json` | flag | Display results in JSON format. Implies `--no-track`. |
| `-r`, `--recursive` | flag | Scan directories recursively for dependency files. |
#### Run
**Usage Example:**
```sh
twyn run
```
or get help with
```sh
twyn run --help
```
#### JSON format
If you want your output in JSON format, you can run `Twyn` with the following flag:
```python
twyn run --json
```
This will output:
```json
{"results":[{"errors":[{"dependency":"my-package","similars":["mypackage"]}],"source":"manual_input"}]}
```
If `Twyn` was run by manually giving it dependencies (with `--dependency`), the source will be `manual_input`.
In any other case (when dependencies are parsed from a file), the source will be the path to the dependencies file. One entry will be created for every source.
### Using Twyn as a library
#### Installation
`Twyn` also supports being used as 3rd party library for you project. To install it, run:
```sh
pip install twyn
```
Example usage in your code:
```python
from twyn import check_dependencies
typos = check_dependencies()
for typo in typos.errors:
print(f"Dependency:{typo.dependency}")
print(f"Did you mean any of [{','.join(typo.similars)}]")
```
#### Logging level
By default, logging is disabled when running as a 3rd party library. To override this behaviour, you can:
```python
logging.basicConfig(level=logging.INFO)
logging.getLogger("twyn").setLevel(logging.INFO)
```
## Configuration
### Allowlist
It can happen that a legitimate package known by the user raises an error because it is too similar to one of the most trusted ones. Imagine that you are using internally a package that you developed called `reqests`. You can then add this packages to the `allowlist`, so it will not be reported as a typo:
```sh
twyn allowlist add
```
To remove it simply:
```sh
twyn allowlist remove
```
### Dependency files
To specify a dependency file through the command line run:
```sh
twyn run --dependency-file
```
The following dependency file formats are supported:
- `requirements.txt`
- `poetry.lock` (<1.5, >=1.5)
- `uv.lock`
- `package-lock.json` (v1, v2, v3)
- `yarn.lock` (v1, v2)
- `pnpm-lock.yaml` (v9)
- `Dockerfile`
- `docker-compose.yml`, `docker-compose.yaml`, `compose.yml`, `compose.yaml` (v1, v2, v3)
### Check dependencies introduced through the CLI
You can also check a dependency by entering it through the command line:
```sh
twyn run --dependency
```
It does accept multiple dependencies at a time:
```sh
twyn run --dependency --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
```sh
twyn run --selector-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 `twyn.toml` file in your working directory when it's trying to load your configurations. If it does not find it, it will fallback to `pyproject.toml`.
However, you can specify a config file as follows:
```sh
twyn run --config
```
All the configurations available through the command line are also supported in the config file.
```toml
[tool.twyn]
dependency_file="/my/path/requirements.txt" # it can be either a string or a list of strings
selector_method="first_letter"
logging_level="debug"
allowlist=["my_package"]
pypi_source="https://mirror-with-trusted-dependencies.com/file-pypi.json"
npm_source="https://mirror-with-trusted-dependencies.com/file-npm.json"
dockerhub_source="https://mirror-with-trusted-dependencies.com/file-dh.json"
```
The file format for each reference is as follows:
```jsonc
{
"date": "string (ISO 8601 format, e.g. 2025-09-10T14:23:00+00)",
"packages": [
{ "name": "string" }
]
}
```
### Cache
By default, `Twyn` will cache the list of trusted packages to a cache file, within the `.twyn` directory that will be automatically created.
You can disable the cache by adding the following flag:
```python
twyn run --no-cache
```
In which case it will download again the list of trusted packages, withou saving them to the cache file.
Cache file is valid for 30 days, after that period it will download again the trusted packages list.
To clear the cache, run:
```python
twyn cache clear
```