# 🛡️ 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
## Installation
### Basic Version (CLI only)
```bash
pip install model-sentinel
```
### GUI Version
```bash
pip install "model-sentinel[gui]"
```
## Usage
### CLI Usage
```bash
model-sentinel --hf ryomo/malicious-code-test
model-sentinel --local ./my-model-directory
model-sentinel --gui --hf ryomo/malicious-code-test
```
### 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
model-sentinel --gui
```
### Python Script Usage
```python
from model_sentinel import verify_hf_model, verify_local_model
# Verify Hugging Face model
result = verify_hf_model("ryomo/malicious-code-test") # Returns True if verified, False otherwise
# Verify local model
result = verify_local_model("./my-model-directory") # Returns True if verified, False otherwise
# Verify with GUI mode
result = verify_hf_model("ryomo/malicious-code-test", gui=True) # GUI window will open
```
## 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. **Hash Update**: Save hash of approved files to `.model-sentinel.json`
## Verification Record
Verified hashes are saved in `.model-sentinel.json`:
```json
{
"hf/ryomo/malicious-code-test@main": {
"revision": "main",
"model_hash": "abc123...",
"files": {
"modeling.py": "def456...",
"configuration.py": "ghi789..."
}
}
}
```
## 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 --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
```
## Technical Specifications
- **Python**: 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.12",
"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/eb/c7/fa18636bddaa66eda0977bd6f7bb6bef10b398016684c1619047ace47432/model_sentinel-0.1.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## 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\nmodel-sentinel --hf ryomo/malicious-code-test\nmodel-sentinel --local ./my-model-directory\nmodel-sentinel --gui --hf ryomo/malicious-code-test\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\nmodel-sentinel --gui\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\nresult = verify_hf_model(\"ryomo/malicious-code-test\") # Returns True if verified, False otherwise\n\n# Verify local model\nresult = verify_local_model(\"./my-model-directory\") # Returns True if verified, False otherwise\n\n# Verify with GUI mode\nresult = verify_hf_model(\"ryomo/malicious-code-test\", gui=True) # GUI window will open\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. **Hash Update**: Save hash of approved files to `.model-sentinel.json`\n\n## Verification Record\n\nVerified hashes are saved in `.model-sentinel.json`:\n\n```json\n{\n \"hf/ryomo/malicious-code-test@main\": {\n \"revision\": \"main\",\n \"model_hash\": \"abc123...\",\n \"files\": {\n \"modeling.py\": \"def456...\",\n \"configuration.py\": \"ghi789...\"\n }\n }\n}\n```\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 --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## Technical Specifications\n\n- **Python**: 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.1.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": "6c877533416a1f4ee254657460f14308164c334dbe650ac473c5a9f3b725f635",
"md5": "4d9636d0b49dcca79f27f76a24eb26ce",
"sha256": "d724179c86c442f222d451a2c2dbcc38d24ae10ef0de8383c0785b99ab80c516"
},
"downloads": -1,
"filename": "model_sentinel-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4d9636d0b49dcca79f27f76a24eb26ce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 20057,
"upload_time": "2025-07-24T11:44:23",
"upload_time_iso_8601": "2025-07-24T11:44:23.560332Z",
"url": "https://files.pythonhosted.org/packages/6c/87/7533416a1f4ee254657460f14308164c334dbe650ac473c5a9f3b725f635/model_sentinel-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ebc7fa18636bddaa66eda0977bd6f7bb6bef10b398016684c1619047ace47432",
"md5": "047fc46809ce202703a570b2e47158fd",
"sha256": "a980a3546c712f11716ed2ff0dfe9b455ef05759e9e5e82a7c5837e4e07ed5b1"
},
"downloads": -1,
"filename": "model_sentinel-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "047fc46809ce202703a570b2e47158fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 13900,
"upload_time": "2025-07-24T11:44:25",
"upload_time_iso_8601": "2025-07-24T11:44:25.049659Z",
"url": "https://files.pythonhosted.org/packages/eb/c7/fa18636bddaa66eda0977bd6f7bb6bef10b398016684c1619047ace47432/model_sentinel-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 11:44:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ryomo",
"github_project": "model-sentinel#readme",
"github_not_found": true,
"lcname": "model-sentinel"
}
JSON
