https://github.com/rogerchappel/containerghost
Local-first CLI for auditing devcontainer, Docker Compose, Dockerfile, package script, and .env.example drift.
https://github.com/rogerchappel/containerghost
cli devcontainer docker-compose drift-detection local-first
Last synced: about 1 month ago
JSON representation
Local-first CLI for auditing devcontainer, Docker Compose, Dockerfile, package script, and .env.example drift.
- Host: GitHub
- URL: https://github.com/rogerchappel/containerghost
- Owner: rogerchappel
- License: mit
- Created: 2026-05-10T08:38:38.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-04T08:25:01.000Z (about 1 month ago)
- Last Synced: 2026-06-04T10:11:18.425Z (about 1 month ago)
- Topics: cli, devcontainer, docker-compose, drift-detection, local-first
- Language: TypeScript
- Size: 61.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ContainerGhost
ContainerGhost is a local-first CLI that audits devcontainer, Docker Compose, Dockerfile, package scripts, and `.env.example` drift before humans or agents burn time in a broken setup.
## Why it exists
Dev environments drift quietly. A devcontainer points at the wrong service, forwarded ports no longer match compose, required env keys disappear, or Dockerfile/package scripts stop lining up. ContainerGhost turns that drift into deterministic local evidence.
## Quick start
```bash
npm install
npm run build
node dist/src/index.js scan examples/basic --out containerghost.md --json containerghost.json
node dist/src/index.js check examples/basic --fail-on missing-env,unknown-service
```
## CLI
```bash
containerghost scan . --out containerghost.md --json containerghost.json
containerghost check . --fail-on missing-env,port-conflict,unknown-service
```
## What it checks in the MVP
- `.devcontainer/devcontainer.json` exists
- `docker-compose.yml` or `compose.yml` exists
- `.env.example` exists and covers `containerEnv` keys
- devcontainer `service` exists in compose services
- forwarded ports exist in compose published ports
- `package.json` includes a `dev` script when Dockerfile + package.json are present
- obvious secrets in text evidence are redacted by default
## Safety model
- Offline and local-first
- No telemetry
- No hidden writes outside explicit output files
- Redaction enabled by default for common token/key/password patterns
## Limitations
- The MVP uses heuristic parsing, not full Docker/devcontainer schema validation
- Port matching currently checks published host ports only
- Secret redaction is pattern-based and intentionally conservative
## Fixture smoke
```bash
npm run smoke
```
This runs a real CLI scan against `examples/basic` and asserts deterministic Markdown and JSON output.
## Verify
Run local verification before opening a PR or publishing:
```bash
npm test
npm run release:check
```
`release:check` runs type-checking, tests, smoke verification, and a dry-run `npm pack` to ensure everything ships cleanly.