Metadata-Version: 2.4
Name: permi
Version: 0.2.12
Summary: AI-powered vulnerability scanner for Nigerian developers and global SMBs
Author-email: Nasarah Peter Dashe <dashenasarahpeter@gmail.com>
License: PERMI COMMUNITY LICENSE
        Version 1.0 — April 2026
        
        Copyright (c) 2026 Nasarah Peter Dashe
        University of Jos, Nigeria
        
        ═══════════════════════════════════════════════════════════════════════════════
        PREAMBLE
        ═══════════════════════════════════════════════════════════════════════════════
        
        Permi was built because Nigerian developers and SMBs deserve world-class
        security tooling that understands their context, their constraints, and their
        market. This license exists to keep Permi free and open for the people it was
        built to serve, while protecting the work that makes it possible.
        
        This license grants broad freedoms for personal, educational, and open-source
        use, while requiring that commercial use — particularly by companies that
        compete directly with Permi or profit from its AI-powered features — obtain a
        separate commercial license.
        
        ═══════════════════════════════════════════════════════════════════════════════
        PART 1 — DEFINITIONS
        ═══════════════════════════════════════════════════════════════════════════════
        
        "Software" means the Permi source code, documentation, rules engine,
        configuration files, and all associated files distributed under this license.
        
        "You" means the individual or legal entity exercising rights under this
        license.
        
        "Commercial Use" means any use of the Software, in whole or in part, that is
        primarily intended for or directed toward commercial advantage or monetary
        compensation. This includes, but is not limited to:
          - Offering the Software as a hosted service (SaaS) to paying customers
          - Selling the Software or a product that bundles the Software
          - Using the Software internally at a for-profit company with more than
            10 employees or more than $50,000 USD in annual revenue
        
        "Non-Commercial Use" means use that is not Commercial Use. This includes:
          - Personal projects and experimentation
          - Academic research and university coursework
          - Open-source projects distributed under an OSI-approved license
          - Use by registered non-profit organisations
          - Use by individual freelancers scanning their own clients' codebases
            as part of a consulting engagement (not resale of the tool itself)
        
        "Derivative Work" means any work that is based on or derived from the
        Software, including modifications, translations, adaptations, or any work
        that incorporates a substantial portion of the Software.
        
        "Contributor" means any individual or entity that submits code, documentation,
        bug reports, or other contributions to the Permi project.
        
        ═══════════════════════════════════════════════════════════════════════════════
        PART 2 — GRANT OF RIGHTS (NON-COMMERCIAL)
        ═══════════════════════════════════════════════════════════════════════════════
        
        Subject to the terms and conditions of this license, the copyright holder
        hereby grants You a worldwide, royalty-free, non-exclusive license to:
        
          1. Use the Software for any Non-Commercial Use without restriction.
        
          2. Copy, modify, and distribute the Software and Derivative Works in
             source or binary form, provided that:
        
             a. You retain this license notice, the copyright notice above, and
                all warranty disclaimers in all copies or substantial portions
                of the Software.
        
             b. Derivative Works distributed to others are licensed under terms
                that are no more permissive than this license.
        
             c. You clearly mark any modified files as changed from the originals,
                including the date of modification and a brief description of
                the changes made.
        
             d. You do not remove, alter, or obscure any attribution notices or
                branding references to Permi or its author in the Software or
                its documentation.
        
          3. Publish, present, and share results produced by the Software,
             provided that you attribute Permi appropriately (see Part 5).
        
        ═══════════════════════════════════════════════════════════════════════════════
        PART 3 — COMMERCIAL USE
        ═══════════════════════════════════════════════════════════════════════════════
        
        Commercial Use of the Software requires a separate written commercial license
        agreement from the copyright holder.
        
        To enquire about a commercial license, contact:
        
          Peter Nasarah Dashe
          Email:  dashenasarahpeter@gmail.com  (or current contact listed at dev.to/peternasarah)
          GitHub: github.com/peternasarah
        
        Commercial licenses are available at reasonable rates and are designed to
        support the continued development of Permi as a free tool for the community.
        
        Companies and individuals engaged in Non-Commercial Use are never required to
        purchase a commercial license.
        
        ═══════════════════════════════════════════════════════════════════════════════
        PART 4 — CONTRIBUTIONS
        ═══════════════════════════════════════════════════════════════════════════════
        
        By submitting a contribution to this project (including pull requests, issues,
        documentation, or code), You agree that:
        
          1. Your contribution is Your original work or You have the right to
             submit it under the terms of this license.
        
          2. You grant the copyright holder a perpetual, worldwide, non-exclusive,
             royalty-free license to use, reproduce, modify, and distribute Your
             contribution as part of the Software under any license the copyright
             holder chooses, including future versions of this license.
        
          3. You understand that your contribution may be used in both the
             community (free) and commercial versions of Permi.
        
          4. You will not be compensated for contributions unless a separate written
             agreement states otherwise.
        
        See CONTRIBUTING.md for contribution guidelines.
        
        ═══════════════════════════════════════════════════════════════════════════════
        PART 5 — ATTRIBUTION
        ═══════════════════════════════════════════════════════════════════════════════
        
        If you use, redistribute, or build upon the Software, you must:
        
          1. Give appropriate credit to Permi and its author:
             "Powered by Bilongstech (github.com/peternasarah/permi) by Peter Nasarah Dashe"
        
          2. Provide a link to this license.
        
          3. Indicate if changes were made.
        
        You may do so in any reasonable manner, but not in any way that suggests the
        copyright holder endorses you or your use.
        
        ═══════════════════════════════════════════════════════════════════════════════
        PART 6 — TRADEMARKS
        ═══════════════════════════════════════════════════════════════════════════════
        
        This license does not grant permission to use the trade name "Permi", the
        Permi logo, or any other trademarks of the copyright holder to endorse or
        promote products derived from this Software without prior written permission.
        
        You may truthfully state that your product "uses Permi" or "is built on Permi"
        provided such statements are accurate and do not imply endorsement.
        
        ═══════════════════════════════════════════════════════════════════════════════
        PART 7 — DISCLAIMER OF WARRANTIES
        ═══════════════════════════════════════════════════════════════════════════════
        
        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, ACCURACY OF SECURITY FINDINGS, AND
        NON-INFRINGEMENT.
        
        PERMI IS A SECURITY ASSISTANCE TOOL. IT DOES NOT GUARANTEE THE DETECTION OF
        ALL VULNERABILITIES IN SCANNED CODE. THE ABSENCE OF FINDINGS DOES NOT IMPLY
        THE ABSENCE OF VULNERABILITIES. YOU ARE RESPONSIBLE FOR VALIDATING ALL
        FINDINGS AND FOR THE SECURITY OF YOUR OWN SYSTEMS.
        
        IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
        DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
        (INCLUDING BUT NOT LIMITED TO PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
        ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
        SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
        ═══════════════════════════════════════════════════════════════════════════════
        PART 8 — TERMINATION
        ═══════════════════════════════════════════════════════════════════════════════
        
        Your rights under this license terminate automatically if you fail to comply
        with any of its terms. Upon termination, you must cease all use and
        distribution of the Software and destroy all copies in your possession.
        
        The copyright holder may reinstate your rights at their discretion upon
        written notice.
        
        ═══════════════════════════════════════════════════════════════════════════════
        PART 9 — GOVERNING LAW
        ═══════════════════════════════════════════════════════════════════════════════
        
        This license shall be governed by and construed in accordance with the laws
        of the Federal Republic of Nigeria, without regard to its conflict of law
        provisions.
        
        ═══════════════════════════════════════════════════════════════════════════════
        
        Built in Nigeria. For Nigeria. Then for the World.
        
        Permi — github.com/peternasarah/permi
        
Project-URL: Homepage, https://github.com/Peternasarah/permi
Project-URL: Repository, https://github.com/Peternasarah/permi
Project-URL: Bug Tracker, https://github.com/Peternasarah/permi/issues
Project-URL: Changelog, https://github.com/Peternasarah/permi/releases
Keywords: security,vulnerability-scanner,static-analysis,SAST,AI,nigeria,cybersecurity,developer-tools,CLI,SQL-injection,XSS,secrets-detection,USSD
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dotenv
Requires-Dist: colorama
Requires-Dist: click
Requires-Dist: requests
Requires-Dist: httpx
Requires-Dist: beautifulsoup4
Dynamic: license-file

# Permi

[![PyPI version](https://badge.fury.io/py/permi.svg)](https://pypi.org/project/permi/)
[![CI](https://github.com/Peternasarah/permi/actions/workflows/ci.yml/badge.svg)](https://github.com/Peternasarah/permi/actions/workflows/ci.yml)

**AI-powered vulnerability scanner for Nigerian developers and global SMBs.**

Permi scans live websites and source code for security vulnerabilities, then uses AI to filter out false positives — so you only see findings that actually matter.

Built in Nigeria. For Nigeria. Then for the world.

---

## Two scan modes

### `--url` — Live web scanning
Point Permi at any website. It crawls the pages, tests for SQL injection, XSS, and checks security headers on the running application.

```bash
permi scan --url https://yoursite.com
```

### `--path` — Static source code scanning
Point Permi at a local folder or GitHub repository. It reads your code files, matches vulnerability patterns, and flags issues before they ship.

```bash
permi scan --path ./myapp
permi scan --path https://github.com/user/repo
```

---

## What Permi detects

### Web scanning (`--url`)
- **SQL Injection** — error-based, boolean-based blind, time-based blind
- **Cross-Site Scripting (XSS)** — reflected XSS with context-aware testing
- **Missing Security Headers** — HSTS, CSP, X-Frame-Options, X-Content-Type-Options
- **Server Information Disclosure** — Server and X-Powered-By header leakage

### Source code scanning (`--path`)
- **SQL Injection** — string concatenation, f-strings, % formatting in queries
- **Cross-Site Scripting** — innerHTML, document.write, Jinja2 |safe filter
- **Hardcoded Secrets** — passwords, API keys, AWS keys, Paystack/Flutterwave secrets
- **Insecure Practices** — eval(), exec(), pickle.loads(), SSL verification disabled, debug mode
- **USSD Vulnerabilities** — unvalidated sessionId, phoneNumber, serviceCode (Nigerian-specific)

---

## Installation

```bash
pip install permi
```

Requires Python 3.9+. Works on Windows, macOS, and Linux.

---

## Usage

**Scan a live website:**
```bash
permi scan --url https://yoursite.com
```

**Scan a local project:**
```bash
permi scan --path ./myapp
```

**Scan a GitHub repository:**
```bash
permi scan --path https://github.com/user/repo
```

**Show only high severity findings:**
```bash
permi scan --url https://yoursite.com --severity high
```

**Export results as JSON:**
```bash
permi scan --url https://yoursite.com --output json
```

**Skip AI filter (offline mode, path scan only):**
```bash
permi scan --path ./myapp --offline
```

**Limit pages crawled (web scan):**
```bash
permi scan --url https://yoursite.com --max-pages 50
```

**Save your API key once (enables AI filtering):**
```bash
permi setup --api-key sk-or-your-key-here
```

**Check your configuration:**
```bash
permi info
```

**Submit feedback:**
```bash
permi feedback
```

---

## Setup — AI false positive filter

Permi uses [OpenRouter](https://openrouter.ai) to filter false positives with AI.
Create a free account, generate an API key, and add it to a `.env` file:

```
OPENROUTER_API_KEY=sk-or-your-key-here
```

No API key? Use `--offline` to skip AI filtering. All raw findings are shown.

---

## Example output — web scan

```
  ██████╗ ███████╗██████╗ ███╗   ███╗██╗
  ██╔══██╗██╔════╝██╔══██╗████╗ ████║██║
  ██████╔╝█████╗  ██████╔╝██╔████╔██║██║
  ██╔═══╝ ██╔══╝  ██╔══██╗██║╚██╔╝██║██║
  ██║     ███████╗██║  ██║██║ ╚═╝ ██║██║
  ╚═╝     ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚═╝

  AI-Powered Vulnerability Scanner
  Built in Nigeria. For Nigeria. Then for the World.

[Permi] Mode     : Web scan (active HTTP testing)
[Permi] Target   : https://testsite.com
[Permi] Crawl    : up to 30 pages

[Permi] Engine found 4 raw finding(s)

[Permi] Running AI filter on 4 finding(s)...

  [1/4] WEB_SQL001 line 0 — REAL  SQL error returned when quote injected into 'id' parameter.
  [2/4] WEB_XSS001 line 0 — REAL  Payload reflected unencoded into HTML response.
  [3/4] WEB_HDR001 line 0 — REAL  Missing HSTS, CSP, and X-Frame-Options headers.
  [4/4] WEB_HDR002 line 0 — FP    Server header present but version not disclosed.

[Permi] Filter complete — 3 real  |  1 false positive(s) removed

────────────────────────────────────────────────────────────────────────
  [1] [HIGH] WEB_SQL001  SQL Injection — Error-based

  URL      : https://testsite.com/search
  Parameter: id
  Payload  : '
  Evidence : DB error: you have an error in your sql syntax
  Why      : Unsanitised input passed directly to a database query.
  AI       : REAL  SQL syntax error confirms user input reaches the query unescaped.

════════════════════════════════════════════════════════════════════════
  SCAN SUMMARY
════════════════════════════════════════════════════════════════════════
  Total findings  : 3  (filtered 1 false positive(s))
  High    : 2
  Medium  : 1
  Low     : 0
════════════════════════════════════════════════════════════════════════
```

---

## Nigerian-specific rules

Permi includes vulnerability rules built specifically for the Nigerian development context — USSD gateway misconfigurations, Paystack and Flutterwave credential exposure, and NDPR-relevant checks. No foreign scanner understands this market the way Permi does.

---

## Built by

Nasarah Peter Dashe — Cybersecurity student, University of Jos, Nigeria.

*Built in Nigeria. For Nigeria. Then for the World.*

---

## Links

- **Website:** [peternasarah.github.io/permi](https://peternasarah.github.io/permi)
- **PyPI:** [pypi.org/project/permi](https://pypi.org/project/permi)
- **Issues:** [github.com/Peternasarah/permi/issues](https://github.com/Peternasarah/permi/issues)
- **Security:** [SECURITY.md](SECURITY.md)
- **License:** [LICENSE](LICENSE)
