TAF (The Archive Framework)
TAF is a framework that aims to provide archival authentication and ensure that Git repositories can be securely cloned/updated. TAF's implementation strongly relies on The Update Framework (TUF), which helps developers maintain the security of a software update system. It provides a flexible framework and specification that developers can integrate into any software update system. TAF integrates Git with TUF:
- TUF targets were modified to authenticate Git commits instead of individual files. This reduces the metadata size and simplifies authentication.
- The TUF metadata repository storage utilizes Git. That means TUF metadata files are stored in a Git repository, which is referred to as an authentication repository.
When a TAF authentication repository is cloned, all target repositories are also cloned, and TUF validation is performed against every commit since the repository's inception. When a TAF repository is updated, data is fetched from upstream and each commit is authenticated. A TAF clone/update differs from a standard Git clone/fetch in that remote commits aren't added to the local Git repositories until they've been fully authenticated locally. TAF can be used to secure any git repository, regardless of its content.
Threats
A git repository can be compromised in several ways:
- An attacker might hack a user's account on a code hosting platform, like GitHub or GitLab.
- An attacker might compromise the hosting platform itself.
- An attacker might gain access to a developer's personal computer.
Such an attacker could then:
- Upload a new GPG key to GitHub.
- Push new commits to any repository.
- Add another authorized user with write access.
- Unprotect the master branch of any repository and force-push to it.
TAF's primary objective is not to prevent the attacks listed above but rather to detect when
an attack has occurred and halt an update if necessary. Thus, TAF should be used instead of
directly calling git pull and git clone.
Further reading
Installation Steps
From PyPI
pip install taf
From source:
pip install -e .
Install extra dependencies when using Yubikey:
pip install taf[yubikey]
Add bash completion:
- copy
taf-complete.shto user's directory - add
source ./taf-complete.shto~/.bash_profileor~/.bashrc - source
~/.bash_profile
Development Setup
We are using pre-commit to run black code formatter, flake8 and bandit code quality checks, as well as Mypy static type checker.
pip install -e .[dev]
pip install -e .[test]
pre-commit install # registers git pre-commit hook
pre-commit run --all-files # runs code formatting and quality checks for all files
NOTE: For Windows users: Open settings.json and replace paths.
Running Tests
To run tests with mocked Yubikey:
pytest
To run tests with real Yubikey:
- Insert test Yubikey
- Run
taf setup_test_keyWARNING: This command will import targets private key to signature slot of your Yubikey, as well as new self-signed x509 certificate! - Run
REAL_YK=True pytestorset REAL_YK=True pytestdepending on platform.
Installing Wheels on Windows and MacOS
The newer versions of TAF do not require additional setup, and there are no platform-specific wheels needed. However, older versions required certain platform-specific DLLs, which the CI would copy to taf/libs before building a wheel. Therefore, it's important to install the appropriate platform-specific wheel if you're using an older version.
Installing Wheels on Ubuntu
- Install dependencies
sudo apt-get update
sudo apt-get install python3 python3-venv python3-dev build-essential swig libpcsclite-dev
sudo apt-get install libssl-dev
sudo apt-get install libykpers-1-dev
- Create virtual environment
python3 -m venv env
pip install --upgrade pip
pip install wheel
pip install taf
- Test CLI
taf
Related Projects
There are projects which share similar ideas to TAF.
gittuf
gittuf is a security layer for Git repositories. gittuf enables a security policy to be specified for a Git repository, such that any user who has read access to the repository may verify compliance with it. While similar in goals, gittuf differs from TAF in its architecture and intended use case.
TAF relies on a multi-repository architecture: TUF metadata resides in an authentication repository, which is used to validate the changes made to any number of target repositories. For detailed information on TAF's architecture, see the TAF architecture document. TAF is intended to verify changes to an archive consisting of any number of Git repositories.
gittuf relies on a Reference State Log (RSL) that encodes a log of repository activity, as well as security policy, loosely based on TUF metadata. This log is then used to enable the validation of every commit in the protected repository. For detailed information on gittuf's architecture, see the gittuf design document. gittuf may be used to verify changes to any single Git repository (multi-repository support is in progress).
Acknowledgements
This project was made possible in part by the Institute of Museum and Library Services (LG-246285-OLS-20)
Release files for taf 0.40.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| taf-0.40.0.tar.gz | 192.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| taf-0.40.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 503.0 kB
Release files / taf-0.40.0.tar.gz
| Download URL | taf-0.40.0.tar.gz |
|---|---|
| Size | 192.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6597091826d10db525b8274b659b146f364cfbf212321b1c1f9fb4d459dc44ef
|
|
BLAKE2b-256 checksum How to use checksums |
d057321d1e532e53223b953bf60288fedbb48860bcde647c1063526e886ce9ce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.8.0 pkginfo/1.13 readme-renderer/46.0 requests/2.34.2 requests-toolbelt/1.0.0 urllib3/2.8.0 tqdm/4.70.1 importlib-metadata/9.0.1 keyring/25.7.0 rfc3986/2.0.0 colorama/0.4.6 CPython/3.10.21
|
Release files / taf-0.40.0-py3-none-any.whl
| Download URL | taf-0.40.0-py3-none-any.whl |
|---|---|
| Size | 310.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0cd5a2fe29c0dcff61b909673d1dfd33077bec92146e7063ea781375d26d0e5e
|
|
BLAKE2b-256 checksum How to use checksums |
816251be3f9a99fc1dd976906a4cb1e9fc6d00e18d7aea3dd6619534a5d9e2a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.8.0 pkginfo/1.13 readme-renderer/46.0 requests/2.34.2 requests-toolbelt/1.0.0 urllib3/2.8.0 tqdm/4.70.1 importlib-metadata/9.0.1 keyring/25.7.0 rfc3986/2.0.0 colorama/0.4.6 CPython/3.10.21
|
