alterks 0.1.0__tar.gz

alterks-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write  # Required for trusted publishing
+
+jobs:
+  publish:
+    name: Build & Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

alterks-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Project
+AlterKS-plan.md
+
+# Build artifacts
+*.dist-info/

alterks-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AlterKS 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.

alterks-0.1.0/PKG-INFO

@@ -0,0 +1,335 @@
+Metadata-Version: 2.4
+Name: alterks
+Version: 0.1.0
+Summary: ALTER KILL SWITCH — Python package scanner, monitor, and supply chain attack mitigation tool.
+Project-URL: Homepage, https://github.com/Wan-Saifudin-DS/AlterKS
+Project-URL: Documentation, https://github.com/Wan-Saifudin-DS/AlterKS#readme
+Project-URL: Repository, https://github.com/Wan-Saifudin-DS/AlterKS
+Project-URL: Issues, https://github.com/Wan-Saifudin-DS/AlterKS/issues
+Author: AlterKS Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: kill-switch,pip,pypi,scanner,security,supply-chain,vulnerability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.24
+Requires-Dist: packaging>=21.0
+Requires-Dist: rich>=12.0
+Requires-Dist: tomli>=1.1; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AlterKS — ALTER KILL SWITCH
+
+[![PyPI version](https://img.shields.io/pypi/v/alterks)](https://pypi.org/project/alterks/)
+[![Python](https://img.shields.io/pypi/pyversions/alterks)](https://pypi.org/project/alterks/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/Wan-Saifudin-DS/AlterKS/actions/workflows/tests.yml/badge.svg)](https://github.com/Wan-Saifudin-DS/AlterKS/actions)
+
+**Python package scanner, monitor, and supply chain attack mitigation tool.**
+
+AlterKS scans your Python dependencies for known vulnerabilities (via [OSV.dev](https://osv.dev)) and suspicious package metadata heuristics, then takes configurable action: **block** installation, **quarantine** to an isolated environment, or **alert** with a warning.
+
+## Why AlterKS?
+
+Supply chain attacks on PyPI are increasing — typosquatting, dependency confusion, and hijacked maintainer accounts are real threats. Existing tools like `pip-audit` and `safety` check for known CVEs, but don't:
+
+- **Block installs before they happen** — AlterKS wraps `pip install` with a pre-scan gate
+- **Score risk heuristically** — detect suspicious packages that have no CVEs yet (typosquats, brand-new single-maintainer packages)
+- **Quarantine instead of just blocking** — isolate risky packages for inspection without polluting your environment
+- **Monitor continuously** — detect newly disclosed vulnerabilities against already-installed packages
+- **Generate constraints** — output pip constraint files to lock down your dependency tree
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         CLI Interface                           │
+│  alterks scan | install | monitor | quarantine | report         │
+├─────────────┬───────────────────────────────────┬───────────────┤
+│  Scanner    │        Heuristic Risk Engine       │   Monitor     │
+│  (scanner)  │         (heuristics)               │  (monitor)    │
+├─────────────┼───────────────────────────────────┼───────────────┤
+│             │       Data Sources Layer           │               │
+│             │  ┌──────────┐  ┌───────────┐      │               │
+│             │  │ OSV.dev  │  │ PyPI JSON │      │               │
+│             │  │  Client  │  │  Client   │      │               │
+│             │  └──────────┘  └───────────┘      │               │
+├─────────────┴───────────────────────────────────┴───────────────┤
+│                      Action Engine                              │
+│            BLOCK  |  QUARANTINE  |  ALERT  |  ALLOW             │
+├─────────────────────────────────────────────────────────────────┤
+│                   Policy Config (pyproject.toml)                │
+│         [tool.alterks] severity, allowlist, actions             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Features
+
+- **Vulnerability scanning** — queries OSV.dev for known CVEs/PYSECs against installed or to-be-installed packages
+- **Heuristic risk scoring** — detects typosquatting, suspiciously new packages, single-maintainer risks, poor metadata quality
+- **Kill switch actions** — block, quarantine, or alert based on configurable severity thresholds
+- **Pre-install protection** — `alterks install <pkg>` scans before pip installs
+- **Continuous monitoring** — scheduled re-scans detect newly disclosed vulnerabilities with JSON and webhook notifications
+- **Quarantine management** — isolate risky packages in separate virtual environments
+- **Constraint generation** — output pip constraint files to block known-bad versions
+- **Policy-driven** — configure everything via `[tool.alterks]` in `pyproject.toml`
+
+## Installation
+
+```bash
+pip install alterks
+```
+
+For development:
+
+```bash
+pip install alterks[dev]
+```
+
+## Quick Start
+
+```bash
+# Scan your current environment
+alterks scan
+
+# Scan a requirements file
+alterks scan -r requirements.txt
+
+# Install a package with pre-install scanning
+alterks install flask
+
+# Start continuous monitoring
+alterks monitor --once
+```
+
+## CLI Reference
+
+### `alterks scan`
+
+Scan installed packages or a requirements file for vulnerabilities and heuristic risks.
+
+```bash
+# Scan current environment (table output)
+alterks scan
+
+# Scan with JSON output
+alterks scan --format json
+
+# Scan with Markdown output
+alterks scan --format markdown
+
+# Scan a requirements file
+alterks scan -r requirements.txt
+```
+
+**Options:**
+- `-r, --requirements FILE` — scan a requirements file instead of the environment
+- `--format [table|json|markdown]` — output format (default: `table`)
+
+**Exit codes:** `0` = all clean, `1` = blocked packages found.
+
+### `alterks install`
+
+Pre-scan a package before installing it with pip. Blocks installation if the scan detects critical issues.
+
+```bash
+# Install with pre-scan
+alterks install requests
+
+# Dry-run (scan only, no install)
+alterks install flask --dry-run
+```
+
+**Options:**
+- `--dry-run` — scan only, do not run pip install
+
+### `alterks quarantine`
+
+Manage packages that have been quarantined to isolated virtual environments.
+
+```bash
+# List quarantined packages
+alterks quarantine list
+
+# Inspect a specific quarantined package
+alterks quarantine inspect <name> <version>
+
+# Release a package from quarantine
+alterks quarantine release <name> <version>
+
+# Remove a quarantined package entirely
+alterks quarantine remove <name> <version>
+```
+
+### `alterks report`
+
+Generate a comprehensive scan report of your environment.
+
+```bash
+# Print JSON report
+alterks report --format json
+
+# Write Markdown report to a file
+alterks report --format markdown -o report.md
+```
+
+**Options:**
+- `--format [table|json|markdown]` — output format (default: `table`)
+- `-o, --output FILE` — write report to a file instead of stdout
+
+### `alterks monitor`
+
+Continuously monitor installed packages for newly disclosed vulnerabilities.
+
+```bash
+# Run a single scan
+alterks monitor --once
+
+# Run every hour
+alterks monitor --interval 3600
+
+# Save reports to a JSON-lines file
+alterks monitor --json-output reports.jsonl
+
+# Send reports to a webhook
+alterks monitor --webhook-url https://example.com/hook
+```
+
+**Options:**
+- `--interval SECONDS` — scan interval (default: `86400` = 24 hours)
+- `--once` — run a single scan and exit
+- `--json-output FILE` — append JSON-lines reports to a file
+- `--webhook-url URL` — POST scan reports to a webhook endpoint
+
+### `alterks generate-constraints`
+
+Generate a pip constraints file that blocks known-vulnerable versions.
+
+```bash
+# Print to stdout
+alterks generate-constraints
+
+# Write to file
+alterks generate-constraints -o constraints.txt
+
+# Then use with pip:
+pip install -c constraints.txt -r requirements.txt
+```
+
+**Options:**
+- `-o, --output FILE` — write constraints to a file instead of stdout
+
+### Global Options
+
+All commands support:
+- `--verbose` — enable debug logging
+- `--quiet` — suppress informational output
+- `--no-color` — disable colored output
+
+## Configuration
+
+Add to your `pyproject.toml`:
+
+```toml
+[tool.alterks]
+# Action per severity: "block", "quarantine", "alert", "allow"
+severity_actions = { critical = "block", high = "block", medium = "alert", low = "allow" }
+
+# Risk score threshold (0-100) — packages above this trigger the configured action
+risk_threshold = 60
+
+# Packages always allowed regardless of scan results
+allowlist = ["my-internal-package"]
+
+# Packages always blocked regardless of scan results
+blocklist = ["known-malicious-pkg"]
+
+[tool.alterks.heuristic_weights]
+typosquatting = 0.30
+package_age = 0.20
+maintainer_count = 0.15
+release_pattern = 0.15
+metadata_quality = 0.20
+```
+
+## Heuristic Risk Factors
+
+| Factor | Weight | What it detects |
+|--------|--------|-----------------|
+| **Typosquatting** | 30% | Name similarity to top 5,000 PyPI packages |
+| **Package age** | 20% | Recently created packages (< 30 days) |
+| **Maintainer count** | 15% | Single-maintainer packages |
+| **Release pattern** | 15% | Unusual version release cadence |
+| **Metadata quality** | 20% | Missing descriptions, URLs, classifiers |
+
+## Development
+
+```bash
+# Clone and install in editable mode
+git clone https://github.com/Wan-Saifudin-DS/AlterKS.git
+cd AlterKS
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/
+
+# Lint
+ruff check src/ tests/
+```
+
+## Project Structure
+
+```
+src/alterks/
+├── __init__.py          # Version, public API
+├── models.py            # Core dataclasses (ScanResult, Vulnerability, PolicyAction)
+├── config.py            # Policy config loader from pyproject.toml
+├── scanner.py           # Scan orchestrator: environment/requirements scanning
+├── heuristics.py        # Composite risk scorer (typosquatting, age, maintainer…)
+├── actions.py           # Kill switch logic: block, quarantine, alert
+├── quarantine.py        # Isolated venv quarantine manager
+├── cli.py               # CLI commands (scan, install, monitor, quarantine, report)
+├── pip_hook.py          # Pip install wrapper with pre-scan
+├── monitor.py           # Continuous monitoring daemon
+├── sources/
+│   ├── osv.py           # OSV.dev API client (single + batch queries)
+│   └── pypi.py          # PyPI JSON API client for metadata heuristics
+└── data/
+    └── top_packages.txt # Bundled top-5,000 PyPI package names (typosquatting)
+```
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/my-feature`)
+3. Run the test suite (`pytest tests/`)
+4. Commit your changes (`git commit -am 'Add my feature'`)
+5. Push to the branch (`git push origin feature/my-feature`)
+6. Open a Pull Request
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.