https://github.com/opensecurity/sigmate-py
Modern CLI for fast, auditable file signing & verification
https://github.com/opensecurity/sigmate-py
checksums ed25519 sbom
Last synced: 2 months ago
JSON representation
Modern CLI for fast, auditable file signing & verification
- Host: GitHub
- URL: https://github.com/opensecurity/sigmate-py
- Owner: opensecurity
- Created: 2025-09-13T17:28:03.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-13T17:28:32.000Z (9 months ago)
- Last Synced: 2025-09-15T21:44:57.344Z (9 months ago)
- Topics: checksums, ed25519, sbom
- Language: Python
- Homepage:
- Size: 70.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
sigmate
A modern, developer-focused CLI for cryptographic file signing and verification.
Explore the features »
Report Bug
·
Request Feature
---
## About The Project
**`sigmate`** provides a fast, understandable, and secure workflow for signing and verifying files. Built for developers, release managers, and security teams, it replaces the complex and often opaque processes of tools like GPG with a streamlined, modern alternative based on Ed25519 cryptography.
The core philosophy is simple: signing should be easy, verification should be trustworthy, and the metadata accompanying a signature should be as valuable as the signature itself. `sigmate` generates structured, auditable artifacts that integrate seamlessly into CI/CD pipelines and supply chain security workflows.
### Why sigmate?
* **Developer-Focused:** Simple, intuitive commands and a configuration model that feels familiar.
* **Transparent & Auditable:** Generates human-readable JSON metadata and CycloneDX-compatible SBOMs alongside raw signatures.
* **Modern Cryptography:** Uses the fast and secure Ed25519 signature algorithm by default.
* **Decoupled Trust:** Manages a local "keyring" for convenience and a separate "trust store" for auditable policy, preventing accidental trust and enhancing security.
---
## 🚀 Getting Started
### Prerequisites
* Python 3.10+
* `pip` and `pipx` (recommended)
### Installation
The recommended way to install `sigmate` is using `pip`, which ensures the tool and its dependencies are isolated from other Python projects.
```bash
pipx install sigmate
````
Alternatively, for development:
```bash
# Clone the repository
git clone https://github.com/opensecurity/sigmate-py.git
cd sigmate
# Install with Poetry
poetry install
```
### First-Time Configuration
Before you start signing, run the interactive `configure` command to set up your default identity and key paths. This is a one-time setup.
```bash
sigmate configure
```
This will prompt you for:
1. **Your default private key** used for signing.
2. **Your default signer identity** (it will try to detect this from your git configuration).
3. The location of your **public key keyring**, where keys of other trusted signers will be stored.
-----
## Core Concepts
`sigmate` manages four key artifacts:
| Artifact | Location (Default) | Purpose |
| ------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------- |
| **Signature** (`.sig`) | `./signatures/` | The raw, binary Ed25519 signature. Provides cryptographic proof of authenticity. |
| **Metadata** (`.meta.json`) | `./signatures/sigmate.meta.json` | A JSON "receipt" for each signing operation, detailing who, what, when, and how. |
| **Keyring** | `~/.config/sigmate/keys/` | A directory of named `.pub` files for trusted public keys, used for convenient verification. |
| **Trust Store** | `~/.config/sigmate/trusted_...json` | An audit log of which key fingerprints are trusted, by whom, and with what status. |
-----
## Usage
### 1. Signing Files
The `sign` command generates cryptographic signatures and metadata for your files.
```bash
# Sign an entire directory, creating both .sig and .meta.json files
sigmate sign --walk ./my-project --both
# Sign a single file with an expiration of 72 hours
sigmate sign --file ./release.zip --expires-in 72 --both
# Sign files and generate a CycloneDX SBOM for supply chain security
sigmate sign --walk ./app --both --sbom
```
### 2. Trusting Other Signers
Before you can verify a signature from someone else, you must explicitly add their public key to your keyring and trust store.
```bash
# Add Alice's public key, give it the name "alice", and record that you added it
sigmate trust add /path/to/alice.pem --name alice --added-by "Your Name"
# Later, update the status of Alice's key to 'verified' after vetting her identity
sigmate trust update --status verified --updated-by "Your Name"
```
### 3. Verifying Signatures
The `verify` command checks the integrity and authenticity of files.
```bash
# Verify a directory using the key of a trusted signer from your keyring
sigmate verify --walk ./downloaded-project --signer alice
# Verify a single file using a specific public key file
sigmate verify --file important.dat --key /path/to/key.pem
# Get a machine-readable JSON report of the verification
sigmate verify --walk ./app --signer alice --json
```
-----
## Command Reference
### `sigmate sign`
* **Target:** Specify files with ``, `--walk `, or `--list `.
* **Output Types:**
* `--raw`: Creates individual `.sig` files.
* `--meta`: Creates a central `sigmate.meta.json`.
* `--both`: Creates both raw and meta artifacts.
* **Key Options:**
* `--key `: Path to the private key (overrides configured default).
* `--identity "Name "`: Signer identity (overrides configured default).
* `--output `: Specify a custom output directory for artifacts.
* `--no-abspath`: Store relative paths in metadata for portability.
### `sigmate verify`
* **Target:** Specify files with ``, `--walk `, or `--list `.
* **Key Source (choose one):**
* `--key `: Use a public key from a specific file path.
* `--signer `: Use a public key from your keyring by its trusted name.
* **Key Options:**
* `--require-trusted`: Fail verification if the signer's key is not marked as 'verified' in the trust store.
* `--sig-type [raw|meta|auto]`: Specify which signature artifact to use.
* `--json`: Output a machine-readable JSON report.
### `sigmate trust`
* `add --name `: Adds a key to the trust store and keyring.
* `list`: Shows all keys in the trust store.
* `update --status `: Changes the verification status of a key (e.g., to `verified` or `revoked`).
* `remove `: Removes a key from the trust store.
### `sigmate configure`
* Run interactively to set up default configuration values (private key, identity, keyring path).
* Run with arguments (`--private-key-path ...`) to set values non-interactively for scripting.
### `sigmate clean`
* `clean`: Removes default artifacts (`./signatures/`, checksum files) from the current directory.
* `clean `: Removes all contents of a specified artifact directory.
-----
## Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
Please see the `CONTRIBUTING.md` file for details on our code of conduct, and the process for submitting pull requests to us.
## License
Distributed under the MIT License. See `LICENSE` for more information.
## Authors
Lucian BLETAN --> Init python project
## Sigmate rust lang
[sigmate](https://github.com/opensecurity/sigmate)
## Contact
Project Link: [sigmate-py](https://github.com/opensecurity/sigmate-py)