Metadata-Version: 2.4
Name: model-sentinel
Version: 0.2.0
Summary: A security verification tool for AI model scripts - Detects and verifies changes in Python files of AI models
Project-URL: Homepage, https://github.com/ryomo/model-sentinel
Project-URL: Repository, https://github.com/ryomo/model-sentinel
Project-URL: Issues, https://github.com/ryomo/model-sentinel/issues
Project-URL: Documentation, https://github.com/ryomo/model-sentinel#readme
Author-email: Ryo Moriwaki <ryomo@duck.com>
Maintainer-email: Ryo Moriwaki <ryomo@duck.com>
License: MIT
License-File: LICENSE
Keywords: ai,code-analysis,huggingface,machine-learning,malware-detection,model-verification,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.12
Requires-Dist: huggingface-hub>=0.33.0
Requires-Dist: platformdirs>=4.3.8
Provides-Extra: gui
Requires-Dist: gradio>=5.37.0; extra == 'gui'
Description-Content-Type: text/markdown

# 🛡️ 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
# Show help and usage instructions
model-sentinel

# Verify Hugging Face model
model-sentinel --hf ryomo/malicious-code-test

# 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
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. **Directory Update**: Save file content and metadata to `.model-sentinel/` directory structure

## Verification Data Directory

Verification data is stored in a structured `.model-sentinel/` directory:

```file
.model-sentinel/
├── registry.json           # Global registry of verified models
├── local/                  # Local models
│   └── {model_name}_{hash}/
│       ├── metadata.json   # Model metadata and file info
│       └── files/          # Individual file content
└── hf/                     # HuggingFace models
    └── {org}/{model}@{revision}/
        ├── metadata.json
        └── files/
```

Example `metadata.json`:

```json
{
  "model_hash": "abc123...",
  "last_verified": "2025-07-28T10:30:00Z",
  "files": {
    "modeling.py": {
      "hash": "def456...",
      "size": 1024,
      "verified_at": "2025-07-28T10:30:00Z"
    }
  }
}
```

## 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
```

## 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.
