modusec 1.0.1

A modular reconnaissance and security auditing framework.

ModuSec v1.0

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

  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:

pip install modusec

From Source (For Development)

1. Clone the repository:

   git clone https://github.com/idevsec/ModuSec.git
   cd ModuSec
   

2. Install in editable mode: Ensure you have Python 3.8+ installed, then run:

   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:

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:

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:

  python -m modusec --url example.com
  

• Scan using selective modules (e.g., security headers and IP exposure only):

  python -m modusec --target example.com --modules headers,ip
  

• Scan multiple targets using a text file:

  python -m modusec --file domains.txt
  

• Specify a custom subdomain wordlist:

  python -m modusec -t example.com -m subdomains -w wordlists/custom.txt
  

• Auto-propagate discovered subdomains:

  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.

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:

# 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/
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
• Shraddha Shinde
• Abhilasha Sharma
• Shashank Pachori

Maintainers:

• IDevSec