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