Metadata-Version: 2.4
Name: uniscan
Version: 0.1.0
Summary: A lightweight CLI tool to audit Unity projects for risky code and binaries.
Author: Tianjiao Li
License: MIT License
        
        Copyright (c) 2025 Tianjiao Li
        
        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.
        
Project-URL: Homepage, https://github.com/TLI-1994/Uniscan
Project-URL: Repository, https://github.com/TLI-1994/Uniscan
Project-URL: Issues, https://github.com/TLI-1994/Uniscan/issues
Keywords: unity,security,static-analysis,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: semgrep>=1.72.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: certifi>=2023.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# Uniscan

**Uniscan** is a **lightweight, read-only command-line interface (CLI) tool** designed to **audit Unity projects** for potentially hazardous code and native binaries. It's a quick and simple way to get a security overview of your project without needing a complex setup. The tool scans C# scripts for risky patterns and provides a clear, color-coded summary directly in your terminal.

### Key Features
* **Static Code Analysis:** Scans C# scripts for common security vulnerabilities and anti-patterns.
* **Binary Detection:** Identifies native binary files (e.g., `.dll`, `.so`, `.dylib`) which can sometimes pose a risk.
* **Clear, Color-Coded Output:** Provides an easy-to-read summary of findings, highlighting issues with different colors.
* **Minimalist Design:** It's read-only, has minimal dependencies, and won't modify your project.

---

## Installation & Usage

You can use Uniscan directly from its source code. No complex installation is required.

### 1. Clone the repository

First, clone the project from GitHub:

```bash
git clone https://github.com/TLI-1994/Uniscan.git
```

### 2. Navigate to the directory
Change your current directory to the cloned repository:
```bash
cd Uniscan
```

### 3. Run the scanner

Run the CLI against your Unity project. From the repository root you can execute the module directly:

```bash
PYTHONPATH=src python -m uniscan.main /path/to/unity/project
```

If you install the package into a virtual environment, the console script becomes available:

```bash
pip install .
uniscan /path/to/unity/project
```

The installation pulls in all required dependencies (including Semgrep and PyYAML).

Common flags:

* `--format {text|json}` – choose human-readable or machine-readable output (`text` is default)
* `--no-colors` – disable ANSI colours in text mode
* `--ruleset path/to/extra_rules.yaml` – load additional Semgrep-style YAML rules (may be passed multiple times)
* `--skip-binaries` / `--include-binaries` – control native binary detection
* `--verbosity {quiet|normal|debug}` – adjust the amount of detail printed (aliases `--quiet` and `--debug`)
* `--engine {auto|semgrep|heuristic}` – force Semgrep, always use the lightweight heuristic scanner, or let Uniscan decide automatically
* `--progress` / `--no-progress` – toggle the live progress indicator (enabled by default)
* `--pretty` / `--no-pretty` – group findings by file and rule for easier human review (default off)

Each run reports which analysis engine was used (`semgrep` when available, otherwise a heuristic fallback) so you can confirm full rule coverage.

Example:

```bash
uniscan ~/Projects/MyUnityGame --format json --skip-binaries
```

### 4. Run the test suite (optional)

Install the testing extra and execute pytest:

```bash
pip install .[test]
python -m pytest
```

---

## License

MIT License — see [LICENSE](../LICENSE) for details.

---

## Developer Notes

Semgrep rules live under `rules/core/semgrep`, one YAML file per rule. Generated rules (such as `unity.autorun.editor-hooks`) are driven by the data in `tools/semgrep/data` and a companion script under `tools/semgrep`. Re-run the generator after editing the spec:

```bash
. venv/bin/activate
python tools/semgrep/generate_autorun_editor_hooks.py
```

Commit both the script changes and the regenerated YAML to keep the rule definitions reproducible.
