From 64d0aee66866400d0c72542ef3d13c28c4c5f439 Mon Sep 17 00:00:00 2001 From: Abdel Fane Date: Thu, 14 May 2026 18:18:10 -0600 Subject: [PATCH] docs: restructure README following opena2a-cli template Plain markdown left-aligned (logo inlined, not centered). First runnable command + simulated output land within the first 30 lines so a new user sees value before scrolling. Commands grouped by job (assess / encrypt / vault / operate) instead of one mixed code block plus a paragraph list, so a reader can scan to the right table directly. The replacement "Which command do I want" intent table consolidates the old "What It Does" + "Common Commands" + "Use Cases" sections. New "Verifying releases" section documents the actual trust signal shipped today: `SHA256SUMS.txt` attached to each GitHub Release. The workflows have `--provenance` + `id-token: write` scaffolding but published artifacts on npm 0.3.4 and PyPI 1.4.3 currently carry no SLSA attestations or Sigstore signatures, so the README does not claim them yet. Drops the centered slogan "Life is hard but cryptography doesn't have to be." and the hardcoded "Python SDK v1.4.3" version string. Census ecosystem count corrected to 11 + NVD (matches `cryptoserve census` help output; the previous "npm, PyPI, crates.io, Go, Maven" listed only five). 246 -> 209 lines. --- README.md | 285 ++++++++++++++++++++++++------------------------------ 1 file changed, 124 insertions(+), 161 deletions(-) diff --git a/README.md b/README.md index 7630f40..7d043f4 100644 --- a/README.md +++ b/README.md @@ -1,146 +1,145 @@ -

- CryptoServe -

+ -

CryptoServe

+# cryptoserve -

- Cryptography as a service. Post-quantum ready, FIPS 140-2/3 compliant, context-driven encryption with zero-config SDKs. -

+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. -

- "Life is hard but cryptography doesn't have to be." -

+[![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) -

- Build Status - License - PyPI - npm -

+[Website](https://cryptoserve.dev) · [Crypto Census](https://census.cryptoserve.dev) · [Docs](https://cryptoserve.dev/docs/) · [SDK](#sdks) · [Self-host](#self-host-optional) -

- Website · - Crypto Census · - Docs · - SDK · - Platform -

- ---- - -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 ` | +| See what cryptography the open-source ecosystem uses | `cryptoserve census` | -Every command supports `--help` for detailed usage. +Run `cryptoserve help` or `cryptoserve --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 ` | 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 ` 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 -- ` | 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'; @@ -149,89 +148,48 @@ 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 @@ -239,8 +197,13 @@ Report vulnerabilities via [GitHub Security Advisories](https://github.com/ecoli ## 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).