Metadata-Version: 2.4
Name: vaultmesh-kabir
Version: 0.1.0
Summary: Zero-trust secrets management SDK
Author: KabirMoulana
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# VaultMesh 🔐

**Zero-trust Secrets Management & Dynamic Credential Rotation Service for Multi-cloud**

[![CI](https://github.com/KabirMoulana/vaultmesh/actions/workflows/ci.yml/badge.svg)](https://github.com/KabirMoulana/vaultmesh/actions)
[![Coverage](https://codecov.io/gh/KabirMoulana/vaultmesh/branch/main/graph/badge.svg)](https://codecov.io/gh/KabirMoulana/vaultmesh)
[![Python 3.12](https://img.shields.io/badge/Python-3.12-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

VaultMesh is a **serverless secrets rotation platform** built on AWS Lambda + Step Functions + EventBridge. It automates credential rotation for RDS, Redis, API keys, and JWT signing keys — with zero standing privileges, full audit trails, and no service downtime during rotation.

## Architecture

```
EventBridge Scheduler (cron)
         │
         ▼
┌─────────────────────┐    ┌─────────────────────────────────────────┐
│ Step Functions      │    │ AWS Secrets Manager                     │
│ Rotation Workflow   │───▶│                                         │
│                     │    │  AWSCURRENT ──→ AWSPREVIOUS             │
│ 1. createSecret     │    │  AWSPENDING ──→ AWSCURRENT  (on finish) │
│ 2. setSecret        │    └─────────────────────────────────────────┘
│ 3. testSecret       │              │ KMS CMK envelope encryption
│ 4. finishSecret     │              ▼
│                     │    ┌─────────────────────┐
│ (retry + catch)     │    │ Lambda Rotators      │
└─────────────────────┘    │ - rds_rotator        │
         │                 │ - redis_rotator      │
         │ on failure      │ - api_key_rotator    │
         ▼                 │ - jwt_rotator        │
      SQS DLQ              └─────────────────────┘
         │
         ▼
   CloudWatch Alarm → SNS → PagerDuty
```

## Rotation Handlers

| Secret Type | Handler | Rotation Mechanism |
|---|---|---|
| RDS (MySQL/Postgres) | `rds_rotator.py` | `ALTER USER` via direct DB connection |
| Redis | `redis_rotator.py` | `CONFIG SET requirepass` via Redis client |
| API Keys | `api_key_rotator.py` | Provider-specific API (GitHub, Stripe, Twilio) |
| JWT Signing Keys | `jwt_rotator.py` | RSA-4096 key pair regeneration, 24h overlap |

All handlers follow the **4-step rotation protocol** (createSecret → setSecret → testSecret → finishSecret), ensuring old credentials remain valid until the new ones are verified.

## Quick Start

```bash
git clone https://github.com/KabirMoulana/vaultmesh
cd vaultmesh
pip install -r requirements.txt

# Run tests (no AWS account needed — uses moto mocks)
pytest tests/unit/ -v --cov=src

# Deploy to AWS
npm install -g aws-cdk@2
cdk deploy VaultMeshStack-dev --app "python infra/cdk/app.py"
```

## Zero Standing Privileges

Each Lambda execution role is scoped to exact secret ARN prefixes:

```json
{
  "Effect": "Allow",
  "Action": [
    "secretsmanager:GetSecretValue",
    "secretsmanager:PutSecretValue",
    "secretsmanager:UpdateSecretVersionStage"
  ],
  "Resource": "arn:aws:secretsmanager:us-east-1:123456789:secret:vaultmesh/*"
}
```

No wildcard `*` resource permissions anywhere in the codebase.

## CI/CD: CDK Diff on PRs

Every pull request gets an automatic CDK diff posted as a comment, showing exactly what infrastructure will change before merge. No surprises in production.

## Threat Model

See [`docs/threat-model/THREAT_MODEL.md`](docs/threat-model/THREAT_MODEL.md) for a complete threat analysis including:
- Attack vectors against the rotation pipeline
- Data classification for managed secrets
- Blast radius analysis per compromise scenario
- Mitigations and compensating controls

This document is intentionally public — security through transparency.

## Project Structure

```
vaultmesh/
├── src/
│   ├── rotators/          # Lambda handlers (one per secret type)
│   ├── handlers/          # API Gateway handlers (admin API)
│   ├── providers/         # Third-party API clients (GitHub, Stripe)
│   ├── models/            # Pydantic models for secret schemas
│   └── utils/             # Crypto utilities, audit logger
├── infra/cdk/
│   ├── app.py             # CDK app entrypoint
│   └── stacks/            # CDK stacks (one per concern)
├── tests/
│   ├── unit/              # Moto-based unit tests (no real AWS)
│   └── integration/       # Tests against real AWS (staging)
└── docs/
    ├── adr/               # Architecture Decision Records
    └── threat-model/      # STRIDE threat model
```

## Architecture Decision Records

- [ADR-001: Lambda vs Fargate for rotation jobs](docs/adr/001-lambda-vs-fargate.md)
- [ADR-002: Step Functions vs EventBridge Pipes](docs/adr/002-step-functions.md)
- [ADR-003: CDK vs Terraform for serverless](docs/adr/003-cdk-vs-terraform.md)

## License

MIT
