# 🛡️ Model Sentinel
A security verification tool for model scripts - Detects and verifies changes in Python files of AI models.
## Features
- **Hugging Face Hub Model Verification**: Detect changes in Python files of remote models
- **Local Model Verification**: Detect changes in model files in local directories
- **Hash-based Verification**: Verify file integrity using hashes
- **Interactive Approval**: Review and approve content of changed files
- **GUI Support**: Intuitive web-based GUI interface
## Quickstart
Get started in seconds:
```bash
pip install "model-sentinel[gui]"
```
Embed verification in your Python script (Hugging Face model example):
```python
from model_sentinel import verify_hf_model
# Launches interactive verification (GUI if gui=True) and exits on rejection for safety.
verify_hf_model("ryomo/malicious-code-test", gui=True)
```
## Installation
### Basic Version (CLI only)
```bash
pip install model-sentinel
```
### GUI Version
```bash
pip install "model-sentinel[gui]"
```
## Usage
### CLI Usage
```bash
# Show help and usage instructions
model-sentinel
# Verify Hugging Face model
model-sentinel --hf ryomo/malicious-code-test
model-sentinel --hf ryomo/malicious-code-test --revision main # optional revision
# Verify local model
model-sentinel --local ./my-model-directory
# List all verified models
model-sentinel --list-verified
# Delete all verification data
model-sentinel --delete
```
### GUI Usage
*Note: GUI commands require the GUI version to be installed.*
```bash
model-sentinel --gui --hf ryomo/malicious-code-test
model-sentinel --gui --local ./my-model-directory
```
### Python Script Usage
```python
from model_sentinel import verify_hf_model, verify_local_model
# Verify Hugging Face model
verify_hf_model("ryomo/malicious-code-test")
# Verify local model
verify_local_model("./my-model-directory")
# Verify with GUI mode
verify_hf_model("ryomo/malicious-code-test", gui=True) # GUI window will open
# Receive boolean result without exiting on rejection
result = verify_hf_model("ryomo/malicious-code-test", exit_on_reject=False)
if result:
print("Model verified. Proceeding...")
else:
print("Verification failed or was rejected.")
```
## Verification Process
1. **Hash Comparison**: Calculate hash of entire model or directory and compare with previous verification
2. **File Verification**: If changes detected, check individual Python files
3. **Content Display**: Show content of changed files (pager in CLI, web interface in GUI)
4. **User Approval**: Only approve if user confirms content is trustworthy
5. **Directory Update**: Save file content and metadata to `.model-sentinel/` directory structure
## Verification Data Directory
Verification data is stored under `.model-sentinel/`.
For the full directory layout and a complete `metadata.json` example, see the spec document: [docs/specs/metadata_v1.md](docs/specs/metadata_v1.md)
## Development
For development and contributing to this project:
```bash
# Clone and setup
git clone https://github.com/ryomo/model-sentinel.git
cd model-sentinel
# Install dependencies
uv sync
# Run from source (for testing)
uv run model-sentinel # Show help
uv run model-sentinel --hf ryomo/malicious-code-test
uv run model-sentinel --local ./my-model-directory
uv run model-sentinel --gui --hf ryomo/malicious-code-test
```
## Testing
This project uses Python's built-in `unittest` for testing.
### Running Tests
Run all tests:
```bash
uv run python -m unittest discover tests -v
```
Run specific test module:
```bash
uv run python -m unittest tests.test_verify.test_verify -v
uv run python -m unittest tests.test_target.test_base -v
uv run python -m unittest tests.test_cli -v
```
### Test Coverage
Generate coverage reports:
```bash
# Run tests with coverage
uv run python -m coverage run -m unittest discover tests
# Generate coverage report
uv run python -m coverage report --include="src/*"
# Generate HTML coverage report
uv run python -m coverage html --include="src/*"
# Open htmlcov/index.html in browser
```
## Publishing
This project uses GitHub Actions to automatically publish to PyPI when a new version tag is pushed.
**Steps:**
1. Run `uv run python scripts/bump_version.py 1.2.3` (replace `1.2.3` with the new version number).
The script will automatically update the version number in the following files:
- `pyproject.toml`
- `src/model_sentinel/__init__.py`
2. Follow the recommended commands shown in the output like below.
```sh
uv sync
git add pyproject.toml src/model_sentinel/__init__.py uv.lock
git commit -m "chore: bump version to v1.2.3"
git push
git tag v1.2.3
git push origin v1.2.3
```
GitHub Actions will build and publish the package to PyPI automatically.
## Technical Specifications
- **Python**: 3.10, 3.11, 3.12+
- **Package Manager**: uv
- **GUI Framework**: Gradio 5.x
- **Hash Algorithm**: SHA-256
- **Supported Files**: Python files (.py)
## License
This project is licensed under the [MIT License](LICENSE).
## Contributing
Pull requests and issue reports are welcome.
Raw data
{
"_id": null,
"home_page": null,
"name": "model-sentinel",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Ryo Moriwaki <ryomo@duck.com>",
"keywords": "ai, code-analysis, huggingface, machine-learning, malware-detection, model-verification, security",
"author": null,
"author_email": "Ryo Moriwaki <ryomo@duck.com>",
"download_url": "https://files.pythonhosted.org/packages/c2/09/4dbf37162744cef8d875107e8374126fdc15f907206ed8e3822ee26a49ce/model_sentinel-0.4.0.tar.gz",
"platform": null,
"description": "# \ud83d\udee1\ufe0f Model Sentinel\n\nA security verification tool for model scripts - Detects and verifies changes in Python files of AI models.\n\n## Features\n\n- **Hugging Face Hub Model Verification**: Detect changes in Python files of remote models\n- **Local Model Verification**: Detect changes in model files in local directories\n- **Hash-based Verification**: Verify file integrity using hashes\n- **Interactive Approval**: Review and approve content of changed files\n- **GUI Support**: Intuitive web-based GUI interface\n\n## Quickstart\n\nGet started in seconds:\n\n```bash\npip install \"model-sentinel[gui]\"\n```\n\nEmbed verification in your Python script (Hugging Face model example):\n\n```python\nfrom model_sentinel import verify_hf_model\n\n# Launches interactive verification (GUI if gui=True) and exits on rejection for safety.\nverify_hf_model(\"ryomo/malicious-code-test\", gui=True)\n```\n\n## Installation\n\n### Basic Version (CLI only)\n\n```bash\npip install model-sentinel\n```\n\n### GUI Version\n\n```bash\npip install \"model-sentinel[gui]\"\n```\n\n## Usage\n\n### CLI Usage\n\n```bash\n# Show help and usage instructions\nmodel-sentinel\n\n# Verify Hugging Face model\nmodel-sentinel --hf ryomo/malicious-code-test\nmodel-sentinel --hf ryomo/malicious-code-test --revision main # optional revision\n\n# Verify local model\nmodel-sentinel --local ./my-model-directory\n\n# List all verified models\nmodel-sentinel --list-verified\n\n# Delete all verification data\nmodel-sentinel --delete\n```\n\n### GUI Usage\n\n*Note: GUI commands require the GUI version to be installed.*\n\n```bash\nmodel-sentinel --gui --hf ryomo/malicious-code-test\nmodel-sentinel --gui --local ./my-model-directory\n```\n\n### Python Script Usage\n\n```python\nfrom model_sentinel import verify_hf_model, verify_local_model\n\n# Verify Hugging Face model\nverify_hf_model(\"ryomo/malicious-code-test\")\n\n# Verify local model\nverify_local_model(\"./my-model-directory\")\n\n# Verify with GUI mode\nverify_hf_model(\"ryomo/malicious-code-test\", gui=True) # GUI window will open\n\n# Receive boolean result without exiting on rejection\nresult = verify_hf_model(\"ryomo/malicious-code-test\", exit_on_reject=False)\nif result:\n print(\"Model verified. Proceeding...\")\nelse:\n print(\"Verification failed or was rejected.\")\n```\n\n## Verification Process\n\n1. **Hash Comparison**: Calculate hash of entire model or directory and compare with previous verification\n2. **File Verification**: If changes detected, check individual Python files\n3. **Content Display**: Show content of changed files (pager in CLI, web interface in GUI)\n4. **User Approval**: Only approve if user confirms content is trustworthy\n5. **Directory Update**: Save file content and metadata to `.model-sentinel/` directory structure\n\n## Verification Data Directory\n\nVerification data is stored under `.model-sentinel/`.\n\nFor the full directory layout and a complete `metadata.json` example, see the spec document: [docs/specs/metadata_v1.md](docs/specs/metadata_v1.md)\n\n## Development\n\nFor development and contributing to this project:\n\n```bash\n# Clone and setup\ngit clone https://github.com/ryomo/model-sentinel.git\ncd model-sentinel\n\n# Install dependencies\nuv sync\n\n# Run from source (for testing)\nuv run model-sentinel # Show help\nuv run model-sentinel --hf ryomo/malicious-code-test\nuv run model-sentinel --local ./my-model-directory\nuv run model-sentinel --gui --hf ryomo/malicious-code-test\n```\n\n## Testing\n\nThis project uses Python's built-in `unittest` for testing.\n\n### Running Tests\n\nRun all tests:\n\n```bash\nuv run python -m unittest discover tests -v\n```\n\nRun specific test module:\n\n```bash\nuv run python -m unittest tests.test_verify.test_verify -v\nuv run python -m unittest tests.test_target.test_base -v\nuv run python -m unittest tests.test_cli -v\n```\n\n### Test Coverage\n\nGenerate coverage reports:\n\n```bash\n# Run tests with coverage\nuv run python -m coverage run -m unittest discover tests\n\n# Generate coverage report\nuv run python -m coverage report --include=\"src/*\"\n\n# Generate HTML coverage report\nuv run python -m coverage html --include=\"src/*\"\n# Open htmlcov/index.html in browser\n```\n\n## Publishing\n\nThis project uses GitHub Actions to automatically publish to PyPI when a new version tag is pushed.\n\n**Steps:**\n\n1. Run `uv run python scripts/bump_version.py 1.2.3` (replace `1.2.3` with the new version number).\n\n The script will automatically update the version number in the following files:\n - `pyproject.toml`\n - `src/model_sentinel/__init__.py`\n\n2. Follow the recommended commands shown in the output like below.\n\n ```sh\n uv sync\n git add pyproject.toml src/model_sentinel/__init__.py uv.lock\n git commit -m \"chore: bump version to v1.2.3\"\n git push\n git tag v1.2.3\n git push origin v1.2.3\n ```\n\nGitHub Actions will build and publish the package to PyPI automatically.\n\n## Technical Specifications\n\n- **Python**: 3.10, 3.11, 3.12+\n- **Package Manager**: uv\n- **GUI Framework**: Gradio 5.x\n- **Hash Algorithm**: SHA-256\n- **Supported Files**: Python files (.py)\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n## Contributing\n\nPull requests and issue reports are welcome.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A security verification tool for AI model scripts - Detects and verifies changes in Python files of AI models",
"version": "0.4.0",
"project_urls": {
"Documentation": "https://github.com/ryomo/model-sentinel#readme",
"Homepage": "https://github.com/ryomo/model-sentinel",
"Issues": "https://github.com/ryomo/model-sentinel/issues",
"Repository": "https://github.com/ryomo/model-sentinel"
},
"split_keywords": [
"ai",
" code-analysis",
" huggingface",
" machine-learning",
" malware-detection",
" model-verification",
" security"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e0ce3a2347d0886b68d106e9a21a089423747211c18377bf4e64c946b8bc1ab8",
"md5": "d38c950f4ef916653a42c795ea90ba66",
"sha256": "28932a5ace43609455d22253d0741b191bda1444481777d214f57249cb54df31"
},
"downloads": -1,
"filename": "model_sentinel-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d38c950f4ef916653a42c795ea90ba66",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 26889,
"upload_time": "2025-08-15T02:41:46",
"upload_time_iso_8601": "2025-08-15T02:41:46.453653Z",
"url": "https://files.pythonhosted.org/packages/e0/ce/3a2347d0886b68d106e9a21a089423747211c18377bf4e64c946b8bc1ab8/model_sentinel-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c2094dbf37162744cef8d875107e8374126fdc15f907206ed8e3822ee26a49ce",
"md5": "d79fcd7aaf93e97b5407ad8b8461395f",
"sha256": "9f6ef76479ed12b098f18bd1359ab935ca229f64758292fdae38cc395501d222"
},
"downloads": -1,
"filename": "model_sentinel-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "d79fcd7aaf93e97b5407ad8b8461395f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19526,
"upload_time": "2025-08-15T02:41:47",
"upload_time_iso_8601": "2025-08-15T02:41:47.670662Z",
"url": "https://files.pythonhosted.org/packages/c2/09/4dbf37162744cef8d875107e8374126fdc15f907206ed8e3822ee26a49ce/model_sentinel-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 02:41:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ryomo",
"github_project": "model-sentinel#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "model-sentinel"
}
JSON
