Metadata-Version: 2.4
Name: owlmind-sec
Version: 2.1.0
Summary: Security scanner with auto-fix. 243 detectors, 30 fixers, 12 languages.
Home-page: https://github.com/MuraveyApp/charwiz
Author: ChampChamp
Author-email: abiwiner520@gmail.com
License: Proprietary
Project-URL: Source, https://github.com/MuraveyApp/charwiz
Project-URL: Bug Tracker, https://github.com/MuraveyApp/charwiz/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

# OwlSec -- Security Scanner

**243 detectors . 30 auto-fixers . 12 languages . Compliance reporting**

OwlSec is a static application security testing (SAST) engine built into
the OwlMind platform. It scans source code for vulnerabilities, maps
findings to CWE identifiers and compliance frameworks, and can
automatically patch many common issues.

---

## Quick Start

```python
from owlmind.owlsec import OwlSec

sec = OwlSec()
report = sec.scan("/path/to/project")
print(report.to_markdown())
```

Fix critical vulnerabilities in one call:

```python
report = sec.scan_and_fix("/path/to/project", critical_only=True)
```

---

## Installation

OwlSec ships as part of the `owlmind` package. No additional
dependencies are required for the core scanner.

```bash
pip install owlmind
```

---

## Usage

### Python API

```python
from owlmind.owlsec import OwlSec

sec = OwlSec()

# Basic scan
report = sec.scan("/path/to/project")

# Parallel scan (default), skip test files
report = sec.scan("/path/to/project", skip_tests=True)

# Dry-run: show what would be fixed without modifying files
report = sec.scan("/path/to/project", fix=True, dry_run=True)

# Scan and auto-fix all fixable issues
report = sec.scan("/path/to/project", fix=True)

# Output formats
print(report.to_markdown())       # human-readable Markdown
print(report.to_json(indent=2))   # JSON
sarif = report.to_sarif()         # SARIF 2.1.0 dict
```

### CI/CD Integration

**GitHub Actions:**

```yaml
- name: OwlSec Security Scan
  run: |
    python -c "
    import json, sys
    from owlmind.owlsec import OwlSec
    report = OwlSec().scan('.', skip_tests=True)
    # Write SARIF for GitHub Code Scanning
    with open('owlsec.sarif', 'w') as f:
        json.dump(report.to_sarif(), f)
    if report.critical_count:
        print(f'BLOCKED: {report.critical_count} critical vulnerabilities')
        sys.exit(1)
    "

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: owlsec.sarif
```

**Pre-commit hook (auto-generated):**

```python
sec = OwlSec()
sec.generate_git_hook("/path/to/project")
# Installs .git/hooks/pre-commit that blocks on critical findings
```

---

## Detectors by Language

| Language            | Detectors | File Extensions                     |
|---------------------|-----------|-------------------------------------|
| Python              | 69        | `.py`                               |
| JavaScript / TypeScript | 35    | `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs` |
| PHP                 | 20        | `.php`, `.phtml`, `.inc`            |
| Java                | 17        | `.java`, `.jsp`, `.properties`      |
| Go                  | 16        | `.go`                               |
| Infrastructure (IaC)| 16        | `.yml`, `.yaml`, `.tf`, `.json`     |
| Ruby                | 15        | `.rb`, `.erb`, `.rake`              |
| Rust                | 11        | `.rs`                               |
| C#                  | 10        | `.cs`, `.cshtml`, `.csx`            |
| Docker              | 9         | `Dockerfile`, `.dockerfile`         |
| Kotlin              | 9         | `.kt`, `.kts`                       |
| Swift               | 8         | `.swift`                            |
| Advanced (cross-lang)| 8        | (applied contextually)              |

**Total: 243 detectors** (plus 1 business-logic analyser applied contextually).

---

## Auto-Fixers (30)

The fixer engine can automatically patch these vulnerability classes:

| # | Fixer                          | Typical CWE  |
|---|--------------------------------|--------------|
| 1 | Hardcoded secret               | CWE-798      |
| 2 | SQL injection                  | CWE-89       |
| 3 | Code injection                 | CWE-94       |
| 4 | XSS                            | CWE-79       |
| 5 | Weak cryptography              | CWE-327      |
| 6 | Insecure deserialization       | CWE-502      |
| 7 | Path traversal                 | CWE-22       |
| 8 | Debug exposure                 | CWE-215      |
| 9 | SSRF                           | CWE-918      |
| 10| CSRF                           | CWE-352      |
| 11| Race condition                 | CWE-362      |
| 12| Open redirect                  | CWE-601      |
| 13| Unsafe YAML loading            | CWE-502      |
| 14| Insecure deserialization (pickle) | CWE-502   |
| 15| SSRF URL validation            | CWE-918      |
| 16| Path traversal (realpath)      | CWE-22       |
| 17| Insecure redirect              | CWE-601      |
| 18| Missing CSRF token             | CWE-352      |
| 19| Insecure tempfile              | CWE-377      |
| 20| Debug exposure (generic)       | CWE-215      |
| 21| Hardcoded URLs                 | CWE-798      |
| 22| Insecure randomness            | CWE-330      |
| 23| Missing input validation       | CWE-20       |
| 24| Log injection                  | CWE-117      |
| 25| JWT none algorithm             | CWE-345      |
| 26| CORS wildcard                  | CWE-942      |
| 27| Cookie security                | CWE-614      |
| 28| Subprocess shell injection     | CWE-78       |
| 29| Format string                  | CWE-134      |
| 30| fix_all (batch apply)          | --           |

All fixes use **atomic transactions** (`AtomicFixer`) so files are
either fully patched or left untouched.

---

## Compliance Standards

OwlSec maps every finding to controls in four compliance frameworks:

- **SOC 2 Type II** -- CC6.x access controls, CC7.x system operations
- **PCI DSS v4.0** -- Requirements 6.2, 6.5 (secure development)
- **HIPAA Security Rule** -- 164.312 technical safeguards
- **ISO/IEC 27001:2022** -- Annex A controls (A.8.24 cryptography, A.8.28 secure coding)

Generate a compliance report:

```python
from owlmind.owlsec.compliance import ComplianceReporter

reporter = ComplianceReporter()
compliance = reporter.evaluate(report)
# Returns per-standard pass/fail/warning with executive summary
```

---

## FP Suppression

OwlSec supports three suppression mechanisms to handle false positives.

### Inline comments

Add a comment on the same line or the line above:

```python
password = "test"  # owlsec-ignore CWE-798
```

Works with `#`, `//`, and `/* */` comment styles.

### .owlsecignore file

Place a `.owlsecignore` file in the project root:

```
# Suppress all findings in test files
tests/**

# Suppress specific CWE in a file
config/settings.py CWE-798

# Suppress specific line
src/legacy.py CWE-89 line:42
```

### .owlsec.yml configuration

```yaml
suppress:
  - file: "tests/**"
    reason: "Test fixtures contain intentional vulnerable patterns"
  - file: "src/legacy.py"
    cwe: CWE-89
    line: 42
    reason: "Parameterised query confirmed safe by review"
```

---

## Configuration

### Scan options

```python
report = sec.scan(
    workspace="/path/to/project",
    fix=False,            # auto-fix after scan
    parallel=True,        # multi-threaded scanning (default)
    max_workers=4,        # thread pool size
    dry_run=False,        # report-only mode
    skip_tests=False,     # ignore test files
)
```

### Skipped directories

The following directories are always excluded from scanning:

`.git`, `.hg`, `.svn`, `__pycache__`, `node_modules`, `.venv`,
`venv`, `.tox`, `.mypy_cache`, `.pytest_cache`, `dist`, `build`,
`.eggs`, `*.egg-info`

---

## Comparison

| Feature                     | OwlSec | Semgrep | Bandit | Snyk Code |
|-----------------------------|--------|---------|--------|-----------|
| Languages                   | 12     | 30+     | 1 (Python) | 10+    |
| Detectors                   | 243    | 2000+   | ~100   | Proprietary |
| Auto-fix                    | 30     | Autofix | No     | Limited   |
| Atomic rollback             | Yes    | No      | No     | No        |
| Compliance mapping          | 4 frameworks | No | No   | Limited   |
| SARIF output                | Yes    | Yes     | Yes    | Yes       |
| Self-learning (FP tuning)   | Yes    | No      | No     | No        |
| Taint tracking              | Yes    | Yes     | No     | Yes       |
| Zero config                 | Yes    | Rules needed | Yes | Cloud needed |
| Offline / air-gapped        | Yes    | Yes     | Yes    | No        |
| Cost                        | Included | Free/Paid | Free | Paid    |

OwlSec is purpose-built for fast, opinionated scanning with built-in
remediation. For projects that need breadth across 30+ languages,
Semgrep is a strong complement. OwlSec differentiates on auto-fix with
atomic rollback, compliance mapping, and self-learning FP reduction.

---

## Contributing

1. **Add a detector** -- Create a `detect_<name>(content, file_path)` function
   in the appropriate `lang_*.py` or `detector.py` module. It must return a
   `list[Vulnerability]`.

2. **Add a fixer** -- Add a `fix_<name>` method to `SecurityFixer` in
   `fixer.py`. Set `auto_fixable=True` on corresponding detector findings.

3. **Register the detector** -- Add it to the `run_*_detectors()` aggregator
   in the language module.

4. **Add tests** -- Place tests in the project test suite covering both
   detection and false-positive suppression.

5. **Compliance mapping** -- If the vulnerability maps to a compliance control,
   add the CWE mapping in `compliance.py`.
