Metadata-Version: 2.4
Name: modusec
Version: 1.0.2
Summary: A modular reconnaissance and security auditing framework.
Author: Madhura Suryawanshi, Shraddha Shinde, Abhilasha Sharma, Shashank Pachori
Maintainer: IDevSec
License-Expression: Apache-2.0
Project-URL: Homepage, https://idevsec.com
Project-URL: Repository, https://github.com/idevsec/ModuSec
Project-URL: Bug Tracker, https://github.com/idevsec/ModuSec/issues
Keywords: security,reconnaissance,scanner,vulnerability,auditing,recon,plugin-based
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.7.0
Requires-Dist: dnspython>=2.6.1
Dynamic: license-file

#  ModuSec v1.0

[![PyPI Version](https://img.shields.io/pypi/v/modusec.svg)](https://pypi.org/project/modusec/1.0.2/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/modusec.svg)](https://pypi.org/project/modusec/)
[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()
[![Security Audits](https://img.shields.io/badge/security-vetted-success.svg)]()

ModuSec is a lightweight, plugin-based reconnaissance and security auditing framework. Written in Python, it allows developers, security enthusiasts, and students to perform fast, modular scanning on target domains to assess security headers, clickjacking protections, subdomain exposures, Google dork vectors, and IP metadata.

Designed to be beginner-friendly yet highly extensible, ModuSec separates scanning logic into independent plugins managed by an execution engine.

---

## Key Features

*   **Pluggable Architecture:** Completely modular scan design. Adding a new scanning capability is as simple as dropping a Python plugin into the `src/modusec/modules/` folder.
*   **Security Headers Audit:** Evaluates standard security headers (`HSTS`, `CSP`, `X-Frame-Options`, `X-Content-Type-Options`, `Referrer-Policy`, and `Permissions-Policy`) with severity recommendations.
*   **Clickjacking Checker:** Probes target URLs for frame resistance using both HTTP headers and custom Content-Security-Policy directive parsers.
*   **Google Dorks Generator:** Automatically constructs targeted Google Dork queries across files, administration panels, errors, and indexing directories for deep passive reconnaissance.
*   **Subdomain Enumeration:** Discovers active subdomains using multi-threaded DNS brute force resolving against custom wordlists.
*   **IP Metadata Resolver:** Collects forward and reverse DNS entries, flagging direct server origin exposures.
*   **Security Hygiene Prober:** Audits basic P5 exposures such as robots.txt and security.txt, and validates Secure/HttpOnly flags on cookies.
*   **CORS/Access-Control Auditor:** Evaluates Cross-Origin Resource Sharing rules.
*   **GraphQL Introspection Scanner:** Detects enabled introspection endpoints at /graphql.
*   **Open Redirect Finder:** Probes path-based redirect parameters.
*   **CRLF Injection Finder:** Scans for HTTP response splitting vulnerabilities.
*   **IDOR Vulnerability Scanner:** Probes endpoints for Insecure Direct Object Reference vulnerabilities using parameter tampering, Base64 ID detection, and unauthenticated/cross-user differential check baselines.
*   **Unified Multi-Format Reporting:** Saves scan reports automatically in standard JSON, clean TXT, and professional Markdown (`.md`) formats.

---

##  Screenshots & UI

*(Screenshots will be uploaded here on release)*

### Interactive Console Mode
```text
  ModuSec v1  Main Menu
  
  1. New Scan
  2. View Scan Queue
  3. Run All Scans
  4. View Past Reports
  5. List Available Modules
  6. Exit
```

---

##  Installation

### From PyPI (Recommended)
You can install ModuSec directly from [PyPI](https://pypi.org/project/modusec/):
```bash
pip install modusec
```

### From Source (For Development)
1. **Clone the repository:**
   ```bash
   git clone https://github.com/idevsec/ModuSec.git
   cd ModuSec
   ```

2. **Install in editable mode:**
   Ensure you have Python 3.8+ installed, then run:
   ```bash
   pip install -e .
   ```

---

##  Usage Guide

ModuSec can be executed in three modes: **Desktop GUI Application** (highly visual), **Interactive Terminal Wizard** (ideal for terminal users), or **Non-Interactive CLI** (ideal for scripting and automation).

### 1. Desktop GUI Application
Launch the visual dark-themed desktop app to configure and run scans graphically:
```bash
python -m modusec --gui
```
*(Alternatively, you can run `python src/modusec/cli.py --gui`)*

### 2. Interactive Terminal Wizard
Run the tool using the package entry point to start the interactive wizard:
```bash
python -m modusec --interactive
```
*(Alternatively, you can run `python src/modusec/cli.py --interactive`)*

The wizard will guide you through target entry, module toggles, individual check selections, scope restriction file loading, and scan execution.

### 3. CLI Automation Mode
Perform rapid single-target or batch file scans directly from your terminal:

*   **Scan a single domain:**
    ```bash
    python -m modusec --url example.com
    ```
*   **Scan using selective modules (e.g., security headers and IP exposure only):**
    ```bash
    python -m modusec --target example.com --modules headers,ip
    ```
*   **Scan multiple targets using a text file:**
    ```bash
    python -m modusec --file domains.txt
    ```
*   **Specify a custom subdomain wordlist:**
    ```bash
    python -m modusec -t example.com -m subdomains -w wordlists/custom.txt
    ```
*   **Auto-propagate discovered subdomains:**
    ```bash
    python -m modusec -t example.com --propagate-subdomains
    ```

---

##  Architecture Diagram

The diagram below outlines the plugin lifecycle, showing how the `ExecutionEngine` pulls plugins from the `Registry` to execute tasks and outputs reports.

```mermaid
graph TD
    CLI[User/CLI Input] -->|Target & Module Config| EE[ExecutionEngine]
    EE -->|Queries| REG[Module Registry]
    REG -->|Dispatches Plugins| H[Headers Plugin]
    REG -->|Dispatches Plugins| C[Clickjacking Plugin]
    REG -->|Dispatches Plugins| D[Dorks Plugin]
    REG -->|Dispatches Plugins| S[Subdomains Plugin]
    REG -->|Dispatches Plugins| IP[IP Exposure Plugin]
    REG -->|Dispatches Plugins| HYG[Hygiene Plugin]
    REG -->|Dispatches Plugins| CORS[CORS Plugin]
    REG -->|Dispatches Plugins| GQ[GraphQL Plugin]
    REG -->|Dispatches Plugins| OR[Open Redirect Plugin]
    REG -->|Dispatches Plugins| CRLF[CRLF Injection Plugin]
    
    H & C & D & S & IP & HYG & CORS & GQ & OR & CRLF -->|Structured Dict Output| EE
    EE -->|Aggregated Results| CORR[Correlation Engine]
    CORR -->|Computes Risk Rating| EE
    EE -->|Dispatches Final Job| REP[Reporter]
    
    REP -->|Generates JSON| R1[Downloads/modusec/output/scan_*.json]
    REP -->|Generates TEXT| R2[Downloads/modusec/output/scan_*.txt]
    REP -->|Generates Markdown| R3[Downloads/modusec/output/scan_*.md]
```

---

##  Report Examples

All scans generate comprehensive reports saved to the `Downloads/modusec/output/` folder by default (or a custom output directory if specified). Below is an example of the newly generated **Markdown Report** (`.md`) format:

```markdown
# ModuSec Scan Report  `RF-BB451F`

## Scan Metadata
| Parameter | Details |
|---|---|
| **Scan ID** | `RF-BB451F` |
| **Targets** | httpbin.org |
| **Modules Run** | cors, graphql, open_redirect, crlf_injection |
| **Status** | DONE |

## Overall Risk Rating
**Risk Score:** `2.5 / 10`  
**Risk Level:** `MEDIUM`

### Key Findings
- [CORS] Permissive CORS allows arbitrary Origin: https://evil.com
```

---

##  Roadmap & Future Enhancements

- [ ] **Port Scanning Plugin:** Introduce basic TCP/UDP port scanner.
- [ ] **SSL/TLS Auditing:** Add support for cipher suite strength checking and SSL certificate expiration parsing.
- [ ] **API Endpoint Expose:** Enable a web UI/dashboard and REST API client wrapper.
- [ ] **Concurrent Sub-scanning:** Implement fully async operations using `asyncio` for DNS bruteforce resolution speedups.

---

##  Contributing

Contributions are welcome! If you find bugs, security concerns, or have architectural suggestions:
1. Fork this repository.
2. Create a feature branch (`git checkout -b feature/amazing-feature`).
3. Commit your changes (`git commit -m 'Add amazing feature'`).
4. Push to the branch (`git push origin feature/amazing-feature`).
5. Open a Pull Request.

---

##  Publishing to PyPI

This project is configured to publish automatically to PyPI via GitHub Actions on new release creation.

### One-Time Setup (Trusted Publishing)
1. Go to your project's publishing settings on PyPI: [pypi.org/manage/account/publishing/](https://pypi.org/manage/account/publishing/)
2. Register a new pending publisher for the repository:
   - **PyPI Project Name:** `modusec`
   - **Owner:** `idevsec` (or your GitHub organization/username)
   - **Repository Name:** `ModuSec`
   - **Workflow Name:** `publish.yml`
   - **Environment Name:** `pypi`
3. Save the publisher configuration.

### How to Release
1. Update the version in `pyproject.toml` (e.g. `version = "1.0.2"`) and `src/modusec/__init__.py`.
2. Commit and push the changes to `main`.
3. Create a new Tag and GitHub Release on the repository.
4. The `.github/workflows/publish.yml` GitHub Action will run, build the project, and securely upload the package distributions to PyPI.

---

##  Educational Disclaimer

> [!WARNING]
> ModuSec is created strictly for educational, learning, and academic research purposes. Do not use this tool on any networks, domains, or web applications without the explicit authorization of the owner. Unauthorized scanning constitutes a violation of international hacking laws. The developers assume no liability and are not responsible for any misuse, damage, or legal issues caused by this framework.

---

##  Credits & Authors

Developed by the R&D Interns at **IDevSec**:
* **[Madhura Suryawanshi](https://linkedin.com/in/madhura-suryawanshi-9ba285309)**
* **[Shraddha Shinde](https://linkedin.com/in/shraddha-shinde-21s26)**
* **[Abhilasha Sharma](https://www.linkedin.com/in/abhilasha-sharma-a34907385)**
* **[Shashank Pachori](https://www.linkedin.com/in/rhino0/)**

**Maintainers:**
* **IDevSec**


