Metadata-Version: 2.4
Name: shieldpkg
Version: 0.1.0
Summary: Run package installs in a phantom environment with canary credentials to detect supply-chain attacks.
Project-URL: Homepage, https://github.com/YOUR_USERNAME/shieldpkg-core
Project-URL: Source, https://github.com/YOUR_USERNAME/shieldpkg-core
Project-URL: Issues, https://github.com/YOUR_USERNAME/shieldpkg-core/issues
Author: ShieldPkg Contributors
License: MIT License
        
        Copyright (c) 2026 ShieldPkg Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: canary-token,credential-protection,devtools,npm,phantom,security,supply-chain
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.9
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Description-Content-Type: text/markdown

# ShieldPkg

**Malicious npm packages steal credentials. ShieldPkg makes sure they only steal fake ones.**

Supply-chain attacks like the XZ backdoor and the hundreds of typosquatting packages caught every month share one playbook: install, read `~/.aws/credentials`, POST the key somewhere, and wait. ShieldPkg intercepts that playbook at the environment level — the malicious package runs, but every credential it touches is a monitored trap.

---

## See it in action

```bash
shieldpkg demo
# Watch ShieldPkg catch a credential theft attempt in real time
```

`shieldpkg demo` plants a fake malicious npm package (`evil-logger`) in a temp directory, runs its postinstall script inside the phantom environment, and watches the circuit breaker kill it when the simulated canary fires. No npm network access required — works completely offline.

Pass `--show-source` to display the evil package's source before it runs, or `--trigger-delay N` to control how many seconds before the simulated canary fires (default 8).

<!-- demo.gif — record with `vhs demo.tape` once the terminal session is scripted -->

---

## What it does

1. **Phantom environment** — creates a fake `$HOME` with realistic-looking `.aws/credentials`, `.ssh/id_rsa`, `.npmrc`, and `.gitconfig`. Your real home directory is never visible to the subprocess.
2. **Canary tokens** — plants real AWS key pairs from [canarytokens.org](https://canarytokens.org) inside the phantom home. If a package exfiltrates them and makes even a single AWS API call, you get an alert with the source IP.
3. **Circuit breaker** — polls for canary triggers while the command runs. If a token fires, the process is killed immediately and the event is logged.

---

## Install

```bash
pip install shieldpkg
```

Requires Python 3.9+. Node.js and Rust/Cargo are optional (only needed for `shieldpkg experiment`).

---

## Quick start

```bash
# One-time setup: create the phantom environment and plant canary credentials
shieldpkg init

# Run any package install command inside the phantom environment
shieldpkg run -- npm install some-package
shieldpkg run -- pip install some-package
shieldpkg run -- npx some-cli

# Check phantom home and canary token status
shieldpkg status

# Watch for canary alerts in real time (blocks; use a separate terminal)
shieldpkg monitor
```

If a canary fires during `shieldpkg run`, the process is killed and you see:

```
╔══════════════════════════════════════════════════════╗
║  THREAT DETECTED — Process killed                    ║
║                                                      ║
║  A package attempted to access your credentials.     ║
║  The process was killed before it could exfiltrate.  ║
║                                                      ║
║  Token:   abc123def456…                              ║
║  IP:      198.51.100.42                              ║
║  Channel: HTTP                                       ║
║                                                      ║
║  Your real credentials were not exposed.             ║
╚══════════════════════════════════════════════════════╝
```

---

## How it works

- **Env sanitizer** strips `AWS_*`, `*_TOKEN`, `*_SECRET`, `*_PASSWORD`, `DATABASE_URL`, and `GITHUB_TOKEN` from the subprocess environment before exec. The phantom `$HOME` is injected instead.
- **Canary polling** runs on a background thread during `shieldpkg run`, calling canarytokens.org every 5 seconds (configurable). On trigger, `SIGKILL` is sent to the process group.
- **Audit log** at `~/.shieldpkg/audit.log` records every init, monitor start, trigger, and kill event in append-only JSON-lines format.

---

## Commands

| Command | Description |
|---|---|
| `shieldpkg init` | Create phantom home, generate canary AWS credentials |
| `shieldpkg demo [--trigger-delay N] [--show-source]` | Simulate a supply-chain attack and watch the kill |
| `shieldpkg run -- <cmd>` | Run `<cmd>` in phantom env with active monitoring |
| `shieldpkg status` | Show phantom home and canary token status |
| `shieldpkg monitor [--interval N]` | Poll canarytokens.org every N seconds (default 60) |
| `shieldpkg audit [--last N] [--triggered-only]` | Inspect the audit log |
| `shieldpkg experiment --packages <list>` | Measure JS→Rust transpilation via Strand (research) |

### `shieldpkg experiment` (research feature)

Evaluates whether Strand-Rust-Coder-14B can reliably transpile npm packages to Rust with verified behavioural equivalence. Requires Ollama running locally and `cargo` installed.

```bash
shieldpkg experiment --packages ms,left-pad,is-even,uuid --fuzz-inputs 500
```

---

## Configuration

`~/.shieldpkg/config.yaml` (created automatically on first run):

```yaml
monitor_interval: 5   # seconds between canary polls during shieldpkg run
```

---

## What it doesn't do

- **Not a scanner** — ShieldPkg does not analyse package source code or flag suspicious imports. It assumes packages will run and focuses on limiting damage.
- **Not a firewall** — outbound network calls are not blocked. A malicious package can still exfiltrate the phantom credentials (that's how detection works), but the credentials it steals are traps.
- **Not a sandbox** — the filesystem outside `$HOME` is visible. If a package targets `/etc/passwd`, `/proc`, or absolute paths to well-known credential locations, ShieldPkg won't stop it reading those files.
- **Not a replacement for `npm audit`** — use both. ShieldPkg is a last line of defence, not a substitute for keeping dependencies up to date.

---

## Development

```bash
git clone https://github.com/yourname/shieldpkg-core
cd shieldpkg-core
pip install -e ".[dev]"
pytest -v
```

---

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Command completed cleanly |
| 1 | User error (bad arguments, not initialised) |
| 2 | System error (Ollama not running, cargo not installed, etc.) |

When `shieldpkg run` detects a threat, it exits 1 after killing the process.

---

## Docs

| Document | Description |
|---|---|
| [docs/how-it-works.md](docs/how-it-works.md) | Phantom env, canary tokens, circuit breaker, and honest limitations |
| [docs/faq.md](docs/faq.md) | Common questions about privacy, compatibility, and workflow |
| [docs/roadmap.md](docs/roadmap.md) | Team vault, Strand Rust replacement, credential proxy, network effect |

---

## License

MIT
