# Importing Penelope from exploits

Penelope can be imported as a Python module inside your exploit scripts so that,
the moment your RCE fires, the resulting shell is handled on the **same terminal**
that ran the exploit. No separate listener window needed.

This is handy when you write a PoC/exploit and want a fully interactive session
delivered straight into your script's terminal.

## How it works

Import `penelope` and pick the entry point that matches how you reach the target:

| Payload type    | Penelope call            | What it does                          |
|-----------------|--------------------------|---------------------------------------|
| Reverse shell   | `penelope.Listener()`    | Starts a listener and waits for the target to connect back |
| Bind shell      | `penelope.Connect(host, port)` | Connects out to a listener already running on the target |
| Socket reuse    | `penelope.Session(sock, ip, port)` | Adopts a socket you already have connected (start the core first with `penelope.core.start()`) |

Finish each script with `penelope.start()`. This runs Penelope's interactive
main menu **blocking on the main thread**, which is where it belongs, since the
menu reads input and installs the `SIGINT` handler, so `Ctrl-C` only reaches it
on the main thread.

A couple of options are useful in this scenario (left **commented out** in the
examples so Penelope prints what it's doing and uncomment them once you no longer
need the extra output):

```python
#penelope.options.silent = True          # suppress the banner / extra output
#penelope.options.single_session = True  # exit after the first session ends
```

## Examples

| Script | Scenario |
|--------|----------|
| `exploit_reverse.py` | Target connects back to a Penelope listener (reverse shell) |
| `exploit_bind.py` | Target opens a bind shell, Penelope connects out to it |
| `exploit_socket_reuse.py` | You already hold a connected socket and hand it to Penelope ([#130](https://github.com/brightio/penelope/issues/130)) |

## Running

All three scripts are **self-contained demos that run entirely on localhost**.
No real RCE and no editing required. Instead of attacking a remote host,
each one spawns a local `bash` process that plays the role of the target
(connecting back for the reverse example, opening a bind shell for the bind
example, or reusing an already-established socket for the socket-reuse example)
so you can see Penelope take over the session in your own terminal:

```bash
python3 exploit_reverse.py
# or
python3 exploit_bind.py
# or
python3 exploit_socket_reuse.py
```
