Metadata-Version: 2.4
Name: cveforge
Version: 0.1.0
Summary: Framework that aim to enhance the developer experience for CVEs, malware, scans and reports. Aimed to Red and Blue cybersecurity teams.
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4>=4.14.2
Requires-Dist: daphne>=4.2.1
Requires-Dist: django>=5.2.8
Requires-Dist: packaging>=25.0
Requires-Dist: paramiko>=4.0.0
Requires-Dist: pathspec>=0.12.1
Requires-Dist: pillow>=12.0.0
Requires-Dist: prompt-toolkit>=3.0.52
Requires-Dist: psutil>=7.1.3
Requires-Dist: requests>=2.32.5
Requires-Dist: rich>=14.2.0
Requires-Dist: scapy>=2.6.1
Requires-Dist: watchdog>=6.0.0
Requires-Dist: xmltodict>=1.0.2
Dynamic: license-file

# CVE Forge: The framework for exploits

The goal of this project is to make CVE development fast and easy by providing a framework that allows quick exploit development.

## Quickstart

**NOTE: This is a TODO meaning is YET to be implemented**
```sh
uv init # helps you to work in a virtualenv
uv add cveforge # add the cveforge dependency
uv run cveforge scaffold payload --verbose-name WannaCry # add to the forge DB the path to the current project
uv run cveforge scaffold exploit --verbose-name "RSA Cracking" --cve-name cve_2025_0002 # add to the forge DB the path to the current project
uv run cveforge scaffold command --verbose-name "sftp" # add to the forge DB the path to the current project
uv run cveforge # now whenever we modify the payload, the exploit or the command project the cveforge self-refresh
```

## Developing a Malware or Payload

Please note that even though this software allows to create and use malware is intended for authorized pentesting only, with the idea in mind of helping malware
develop is not causing unauthorize damage but quickly letting clients know how much can impact a vulnerability into their system.

PR including malware WON'T be merged instead malware development is exclusive for the team responsible of developing this software as countermeasure for safe
usage is to be taken (NOTE: this can change in the future when we run this software in an isolated environment)

## Developing a command

As you may have noticed this project is a shell like software, you can use command like ping, ip etc... with the only caveat that all commands are to be made using python, even though we support payload development with Rust, we won't be integrating with Rust for exploits or command as this doesn't offer any benefit
except for speed AFAIC.

Once you do the quickstart step for developing a command you'd have two pieces of structures a ForgeParser and a decorated function.

### The ForgeParser
The parser is the part of the code that parse the user input and turn it into your function requirements or what is the same the part that turns commands flags
into function keywords arguments.

```py
from cveforge import ForgeParser

class YourParser(ForgeParser):
    def setUp(self): # Here you may setup your command metadata as its name and arguments
        self.add_argument("--my-flag")
```

### The command entrypoint
```py
from cveforge import tcve_command
from cveforge import Context
from .parser import YourParser
import logging


@tcve_command("your_command_name", parser=YourParser)
def your_parser(context: Context, my_flag: str):
    logging.info("Running your command with flag '%s'", my_flag)
```

You may never add defaults on your function definition and rather use the parser defined default when adding your argument.

### Usage:
```sh
your_command_name --my-flag "CVE Forge is amazing!!!" # output: info: Running your command with flag 'CVE Forge is amazing!!!'
```

## Developing an Exploit or PoC for CVEs

Developing an exploit is just like creating a command but rather than using the @tcve_command we use the @tcve_exploit like follows:

```py
from cveforge import tcve_exploit

@tcve_exploit("cve_2025_0001", categories=["cve", "privilege escalation"])
def main(context: Context, **kwargs):
    pass
```
Note the categories is also a possible command for the @tcve_command decorator, is useful for allowing the user to search with different queries for your command

## TODO
1. Using the completer along with the command create a feedback event that allows the completer to determine which kind of info display the user

## FIXME: Known Bugs
1. Cannot open two instances at the same time, even if not intended a more user friendly behavior should be implemented
