Skip to content

docs: restructure README following opena2a-cli template #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thebenignhacker merged 1 commit into from
May 15, 2026
Merged

docs: restructure README following opena2a-cli template #45

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
285 changes: 124 additions & 161 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,146 +1,145 @@
<p align="center">
<img src="docs/assets/logo.svg" alt="CryptoServe" width="120" height="120">
</p>
<img src="docs/assets/logo.svg" alt="" width="64" height="64" align="left">

<h1 align="center">CryptoServe</h1>
# cryptoserve

<p align="center">
<strong>Cryptography as a service. Post-quantum ready, FIPS 140-2/3 compliant, context-driven encryption with zero-config SDKs.</strong>
</p>
Cryptographic toolchain for codebases. Scans for weak crypto, generates CBOMs, enforces CI gates, encrypts files, and assesses post-quantum readiness. Works offline. Apache 2.0.

<p align="center">
<em>"Life is hard but cryptography doesn't have to be."</em>
</p>
[![Build](https://img.shields.io/github/actions/workflow/status/ecolibria/cryptoserve/ci.yml?branch=main&label=build)](https://github.com/ecolibria/cryptoserve/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/cryptoserve.svg?label=npm)](https://www.npmjs.com/package/cryptoserve)
[![PyPI](https://img.shields.io/pypi/v/cryptoserve.svg?label=pypi)](https://pypi.org/project/cryptoserve/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

<p align="center">
<a href="https://github.com/ecolibria/cryptoserve/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ecolibria/cryptoserve/ci.yml?branch=main&style=flat-square&label=build" alt="Build Status"></a>
<a href="https://github.com/ecolibria/cryptoserve/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square" alt="License"></a>
<a href="https://pypi.org/project/cryptoserve/"><img src="https://img.shields.io/pypi/v/cryptoserve.svg?style=flat-square" alt="PyPI"></a>
<a href="https://www.npmjs.com/package/cryptoserve"><img src="https://img.shields.io/npm/v/cryptoserve.svg?style=flat-square" alt="npm"></a>
</p>
[Website](https://cryptoserve.dev) · [Crypto Census](https://census.cryptoserve.dev) · [Docs](https://cryptoserve.dev/docs/) · [SDK](#sdks) · [Self-host](#self-host-optional)

<p align="center">
<a href="https://cryptoserve.dev">Website</a> &middot;
<a href="https://census.cryptoserve.dev">Crypto Census</a> &middot;
<a href="https://cryptoserve.dev/docs/">Docs</a> &middot;
<a href="#sdk-usage">SDK</a> &middot;
<a href="#self-hosted-platform">Platform</a>
</p>

---

CryptoServe is an open-source cryptographic platform with three layers:

- **CLI** -- Scan codebases for weak crypto, generate CBOMs, enforce CI/CD gates, encrypt files. Zero dependencies, works offline.
- **SDK** -- Python and Node.js libraries for encryption, hashing, signatures, JWT tokens, and key exchange. Context-aware algorithm selection with post-quantum support (ML-KEM, ML-DSA, SLH-DSA).
- **Platform** -- Self-hosted server with centralized key management, automatic rotation, policy enforcement, FIPS 140-2/3 compliance, and audit logging.

---

## Try It Now
## Quick start

```bash
npx cryptoserve scan .
```

That's it. Scans your project for cryptographic libraries, algorithms, weak patterns, and hardcoded secrets across 6 languages. No config, no server, zero npm dependencies.

```
Found 4 crypto libraries, 3 source algorithms, 1 weak pattern
Quantum readiness: 40/100 (2 quantum-vulnerable algorithms)
CryptoServe scan: .

Found
---------------------------------------------------
Crypto libraries 4
Source algorithms 3 (1 weak: MD5)
Hardcoded secrets 1
---------------------------------------------------
Quantum readiness 40 / 100 (2 quantum-vulnerable)

Next: cryptoserve pqc (migration plan)
cryptoserve cbom (export CBOM)
cryptoserve gate . (block weak crypto in CI)
```

Scans 6 languages (JavaScript/TypeScript, Go, Python, Java/Kotlin, Rust, C/C++) against a database of 131 algorithms. Zero npm dependencies. Works offline.

## Install

```bash
# Node.js (zero dependencies, Node 18+)
npm install -g cryptoserve

# Python
pip install cryptoserve
npx cryptoserve scan . # run once, no install
npm install -g cryptoserve # install globally (Node 18+)
pip install cryptoserve # Python SDK + CLI alias
```

## What It Does

**Scan** -- Find every cryptographic dependency, algorithm, weak pattern, and hardcoded secret in your codebase. Supports JavaScript/TypeScript, Go, Python, Java/Kotlin, Rust, and C/C++.
### From source

**Assess** -- Get a quantum readiness score with SNDL (Store Now, Decrypt Later) risk analysis and migration recommendations based on NIST FIPS 203/204/205 standards.
```bash
git clone https://github.com/ecolibria/cryptoserve.git
cd cryptoserve
node sdk/javascript/bin/cryptoserve.mjs scan . # JS CLI, no build step
```

**Generate** -- Export a Cryptographic Bill of Materials (CBOM) in CycloneDX or SPDX format for supply chain compliance.
The Python SDK lives under `sdk/python/` (editable install via `pip install -e sdk/python`).

**Enforce** -- Add `cryptoserve gate` to your CI pipeline to block builds that use weak algorithms or fail quantum readiness thresholds.
## Verifying releases

## Common Commands
Every published tag carries a `SHA256SUMS.txt` attached to the GitHub Release. Wheels and tarballs match those hashes; npm tarballs match `dist.shasum` from the registry.

```bash
cryptoserve scan . # Scan project (6 languages, 130+ algorithms)
cryptoserve scan . --binary # Include binary signature detection
cryptoserve pqc # Post-quantum readiness assessment
cryptoserve cbom --format cyclonedx # Generate CBOM
cryptoserve gate . --fail-on-weak # CI/CD quality gate
cryptoserve encrypt "secret" -p mypassword # Offline encryption
cryptoserve hash-password --password mypass # Password hashing (CI mode)
cryptoserve vault set API_KEY sk-abc123 # Encrypted secret storage
# Python wheel
gh release download v1.4.3 -p SHA256SUMS.txt -R ecolibria/cryptoserve
sha256sum -c SHA256SUMS.txt

# npm tarball
npm view cryptoserve@0.3.4 dist.shasum dist.tarball
```

See the [full CLI reference](docs/cli.md) for all commands and flags.
The npm and PyPI publish workflows run from a fixed-tag trigger with `id-token: write` and `--provenance`. SLSA provenance attestations and Sigstore signatures are scaffolded in the workflows but not yet propagated to released artifacts; until that ships, verify via `SHA256SUMS.txt`.

## Built-in Help
## Which command do I want

```bash
cryptoserve help # All commands and flags
cryptoserve scan --help # Scan-specific options
cryptoserve --version # Current version
```
| You want to... | Command |
|---|---|
| See what crypto is in this project | `cryptoserve scan .` |
| Score post-quantum readiness and get a migration plan | `cryptoserve pqc` |
| Generate a Cryptographic Bill of Materials | `cryptoserve cbom --format cyclonedx` |
| Block weak crypto in CI | `cryptoserve gate . --fail-on-weak` |
| Encrypt a file or string offline | `cryptoserve encrypt --file data.csv --password $SECRET` |
| Hash a password (scrypt / pbkdf2 / argon2) | `cryptoserve hash-password --algorithm argon2` |
| Store secrets in an encrypted local vault | `cryptoserve vault set API_KEY <value>` |
| See what cryptography the open-source ecosystem uses | `cryptoserve census` |

Every command supports `--help` for detailed usage.
Run `cryptoserve help` or `cryptoserve <command> --help` for full flags.

## Supported Languages
## Commands

| Language | Manifest | Source Detection |
|----------|----------|-----------------|
| JavaScript/TypeScript | `package.json` | Imports, algorithm literals, weak patterns |
| Go | `go.mod` | `crypto/*` stdlib, `x/crypto`, `circl` |
| Python | `requirements.txt`, `pyproject.toml` | `hashlib`, `cryptography`, `PyCryptodome` |
| Java/Kotlin | `pom.xml` | `Cipher.getInstance`, `MessageDigest`, `KeyPairGenerator` |
| Rust | `Cargo.toml` | `aes-gcm`, `ring`, `ed25519-dalek`, `pqcrypto` |
| C/C++ | -- | OpenSSL `EVP_*`, `RSA_*`, `SHA*_Init` |
### Assess

## Use Cases
| Command | What it does |
|---|---|
| `cryptoserve scan [path]` | Find every crypto library, algorithm, weak pattern, and hardcoded secret in the tree. JSON or table output. |
| `cryptoserve pqc` | Quantum-readiness score with SNDL (Store Now, Decrypt Later) analysis and NIST-aligned migration guidance. |
| `cryptoserve cbom [path] --format <fmt>` | Export a CBOM in CycloneDX or SPDX. |
| `cryptoserve gate [path]` | CI/CD quality gate. Non-zero exit on weak algorithms or thresholds failing. SARIF for the GitHub Security tab. |
| `cryptoserve census` | Global crypto adoption across 11 package ecosystems plus NVD. Live dashboard at [census.cryptoserve.dev](https://census.cryptoserve.dev). |

| Scenario | Command | Time |
|----------|---------|------|
| Audit codebase for weak crypto before compliance review | `cryptoserve scan . && cryptoserve cbom --format cyclonedx` | ~30s |
| Block quantum-vulnerable algorithms in CI | `cryptoserve gate . --fail-on-weak --min-score 70` | ~10s |
| Assess post-quantum readiness for your organization | `cryptoserve pqc --profile healthcare --verbose` | ~5s |
| Encrypt a file offline without any server | `cryptoserve encrypt --file data.csv --password $SECRET` | ~1s |
| Generate CBOM for supply chain compliance | `cryptoserve cbom . --format spdx --output cbom.json` | ~15s |
### Encrypt

## CI/CD Integration
| Command | What it does |
|---|---|
| `cryptoserve encrypt "text"` | Context-aware encryption. `--context <name>` picks an algorithm per the policy model; `--password` does pure-password mode. |
| `cryptoserve encrypt --file F --output O` | Encrypt a file in place or to a new path. |
| `cryptoserve decrypt ...` | Inverse of `encrypt`. Same flags. |
| `cryptoserve hash-password` | scrypt by default; `--algorithm argon2` if `cryptoserve[password]` is installed. Non-interactive `--password` for CI. |
| `cryptoserve context list` | Available encryption contexts and the algorithm each resolves to. |

Add to any CI pipeline:
### Vault

```yaml
- name: Crypto gate
run: npx cryptoserve gate . --fail-on-weak --max-risk medium --format sarif
```
| Command | What it does |
|---|---|
| `cryptoserve vault init` | Create an encrypted local secret store. |
| `cryptoserve vault set/get/list/delete` | CRUD against the vault. |
| `cryptoserve vault run -- <cmd>` | Run a subprocess with vault entries injected as env vars. |
| `cryptoserve vault import .env` | Import an existing `.env` file. |

### Operate

The `gate` command exits non-zero when violations are found. Use `--format sarif` to upload results to GitHub's Security tab.
| Command | What it does |
|---|---|
| `cryptoserve init` | One-shot setup: master key, default vault, AI-tool integration. |
| `cryptoserve login [--server URL]` | Authenticate against a self-hosted CryptoServe server. |
| `cryptoserve status` | Configuration, server reachability, vault state. |
| `cryptoserve version` | Build version. |

## Exit Codes
Full reference: [docs/cli.md](docs/cli.md).

| Code | Meaning |
|------|---------|
| `0` | Success (scan clean, gate passed) |
| `1` | Failure (gate failed, crypto issues found, invalid input) |
## CI/CD

---
```yaml
- name: Crypto gate
run: npx cryptoserve gate . --fail-on-weak --max-risk medium --format sarif --output crypto.sarif
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: crypto.sarif
```

## SDK Usage
Exit codes: `0` clean / gate passed, `1` failures found or invalid input.

### Node.js SDK (offline, zero dependencies)
## SDKs

ES module SDK for local scanning, analysis, and encryption. No server required.
### Node.js (offline, zero dependencies)

```javascript
import { scanProject } from 'cryptoserve/lib/scanner.mjs';
Expand All @@ -149,98 +148,62 @@ import { generateCbom, toCycloneDx } from 'cryptoserve/lib/cbom.mjs';
import { encrypt, decrypt } from 'cryptoserve/lib/local-crypto.mjs';
```

See the [Node.js SDK README](sdk/javascript/README.md).
Full reference: [sdk/javascript/README.md](sdk/javascript/README.md).

### Python SDK v1.4.3 (server-connected)

The Python SDK adds managed key management and context-aware algorithm selection when connected to a CryptoServe server:
### Python (server-connected, local fallback)

```bash
pip install cryptoserve # Basic
pip install cryptoserve[password] # With argon2 support
pip install cryptoserve # core + client
pip install cryptoserve[password] # adds argon2
```

```python
from cryptoserve import CryptoServe

crypto = CryptoServe(app_name="my-app", team="platform")

ciphertext = crypto.encrypt(b"data", context="user-pii")
plaintext = crypto.decrypt(ciphertext, context="user-pii")
```

Key features: encrypt/decrypt (bytes and strings), password hashing (scrypt + argon2), JWT tokens, local mode (no server), async support.

See the [Python SDK docs](docs/sdk/python.md).
Local mode works without a server. Full reference: [docs/sdk/python.md](docs/sdk/python.md).

---
## Self-host (optional)

## Self-Hosted Platform

The optional server adds centralized key management, policy enforcement, and a dashboard. The CLI works fully standalone without it.

### Quick start
The CLI and SDKs work fully offline. The self-hosted server adds centralized key management, policy enforcement, audit logging, and a dashboard.

```bash
docker run -d -p 8003:8003 -p 3000:3000 -v cryptoserve-data:/data ghcr.io/ecolibria/crypto-serve
```

API: `http://localhost:8003` | Dashboard: `http://localhost:3000`

### Multi-container (production)

```bash
# Download, inspect, then execute -- don't pipe curl into sh.
curl -fsSL -o quickstart.sh https://raw.githubusercontent.com/ecolibria/crypto-serve/main/scripts/quickstart.sh
shasum -a 256 quickstart.sh # compare against the SHA256 in the release notes
sh quickstart.sh
```

Downloads the compose file, generates secrets, and starts PostgreSQL + backend + frontend. See the [production deployment guide](docs/guides/production-deployment.md).

### Platform features
API on `:8003`, dashboard on `:3000`. For production (Postgres + frontend + backend, generated secrets), see [docs/guides/production-deployment.md](docs/guides/production-deployment.md). Don't pipe `curl | sh`; download `scripts/quickstart.sh`, compare `shasum` against release notes, then execute.

| Feature | Description |
|---------|-------------|
| **Key Management** | Automatic rotation, versioning, HKDF derivation, Shamir secret sharing, HSM/KMS backends |
| **Context Model** | 5-layer algorithm selection: sensitivity, compliance, threats, access patterns, constraints |
| **Policy Engine** | Declarative rules with CI/CD gate enforcement |
| **Multi-Tenancy** | Per-tenant isolation with separate keys and policies |
| **Audit & Compliance** | SIEM integration, FIPS 140-2/3 modes |
| **Identity** | OAuth (GitHub/Google/Azure/Okta), RBAC, SDK token management |

---
Capabilities: automatic key rotation and versioning, HKDF derivation, Shamir secret sharing, HSM/KMS backends, 5-layer context model, declarative policies, OAuth (GitHub/Google/Azure/Okta), RBAC, FIPS 140-2/3 modes, SIEM forwarding.

## Documentation

| Resource | Description |
|----------|-------------|
| [Getting Started](docs/getting-started/index.md) | Installation and quickstart |
| [CLI Reference](docs/cli.md) | All commands, flags, and examples |
| [Python SDK](docs/sdk/index.md) | SDK reference |
| [API Reference](docs/api-reference/index.md) | REST API |
| [Architecture](docs/concepts/architecture.md) | Context model, policy engine, key management |
| [Post-Quantum](docs/concepts/post-quantum.md) | ML-KEM, ML-DSA, SLH-DSA, hybrid key exchange |
| [Security](docs/security/index.md) | FIPS compliance, threat model |

## Global Crypto Census

See what cryptography the open-source ecosystem actually uses:

```bash
npx cryptoserve census
```

Scans npm, PyPI, crates.io, Go, and Maven package registries. Live dashboard at [census.cryptoserve.dev](https://census.cryptoserve.dev).
| Resource | What's there |
|---|---|
| [Getting started](docs/getting-started/index.md) | Install and first scan. |
| [CLI reference](docs/cli.md) | Every command and flag. |
| [Architecture](docs/concepts/architecture.md) | Context model, policy engine, key management. |
| [Post-quantum](docs/concepts/post-quantum.md) | ML-KEM, ML-DSA, SLH-DSA, hybrid key exchange. |
| [Python SDK](docs/sdk/index.md) | API and examples. |
| [REST API](docs/api-reference/index.md) | Server endpoints. |
| [Security](docs/security/index.md) | Threat model, FIPS compliance, transparency. |

## Security

Report vulnerabilities via [GitHub Security Advisories](https://github.com/ecolibria/cryptoserve/security/advisories). See [SECURITY.md](SECURITY.md).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).
Apache 2.0. See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev loop, test conventions, and pre-push review gates.

```bash
git clone https://github.com/ecolibria/cryptoserve.git
cd cryptoserve && npm test
```

## License

Apache License 2.0. See [LICENSE](LICENSE).
Apache 2.0. See [LICENSE](LICENSE).
Loading