port-agent 0.1.1
An AI agent that diagnoses vulnerabilities in network ports using OpenAI's Responses API
License: MIT
Requires Python: >=3.9
Keywords: ai, agent, port, vulnerabilities, diagnostics, openai

# Port Agent

A demonstration project that shows how an agent can become a member of its own development team. In this case, the agent's role is an expert in port vulnerabilities AND a developer that suggests improvements for the toolset.  It's sugestions come as a result of trying to satisfy a customer query. Just as a team member would, it points out what went well and what could have gone better if certain features were added.  


## These prompts were used to enable the Agent to support it's own development. So Cool.
- You are an expert agent for diagnosing open port vulnerabilities on Windows PCs. 
- You are also an important part of the development team. 
- You act as subject-matter-expert to help the other developers improve the tool set. 
- You will be suggesting improvements based on your skills.
- Clearly distingush when your comments are as an agent analyzing ports and when your comments are directed to the developers.



## Why This Example Might Be Useful
If you are developing an agent in an area where you are not expert, this method of pair developemnt can produce a better product than you could do on your own.
I show this tequnique without a framework, it uses the OpenAI API directly. Simpler. 

## Things to Know

This is not a polished, production‑ready agent. It is well into the development cycle and can attack many port issues, but I have deliberatley left it with opportunities for the agent to point out improvents. It is also one reason that I chose vulnerability testing as the vehicle for this project, because it never ends.

I have also left on some of the logging so it is easy to watch the agent choose and combine tools. It is very informative.

A few important constraints: 
  - The agent can only examine ports on **its own local machine**. This is not a network scanner. It is not nmap. 
  - Tools are **read‑only**. Nothing can modify port configurations. 
  - The goal is to demonstrate agent design patterns, not to build a full security scanner.

 ## 10 Interesting Example Prompts for the Agent
 ### (designed to demonstrate the depth of the agent and to surface developer level contributions)

1) **“Port 8000 is open on my PC. Identify what it is and whether it’s exposed beyond localhost. Provide the owning binary path, signature status, and any firewall rules allowing it.”**

   *Tools combined:* `tcp_probe`, `banner_probe`, `http_probe`, `service_probe`, `netstat`, `tasklist`, `get_process_id`, `authentic`, `find_firewall_rules_by_port`, `firewall_settings`

   *Agent analysis:* exposure vs. bind address vs. firewall scope, plus trust assessment of the binary.

2) **“Audit my machine for ‘high-risk’ listening ports (SMB/RDP/WinRM/DBs). For each, map port → PID → process path → signed/unsigned → firewall allow rules.”**
   
   *Tools combined:* `netstat`, `tasklist`, `get_process_id`, `authentic`, `find_firewall_rules_by_port`, `firewall_settings`
   
   *Agent analysis:* prioritization/risk scoring based on common attack surface, plus trust signals.

3) **“This PID is listening on an unknown port. Tell me what service it likely is, whether it’s Microsoft-signed, and whether it’s reachable over the network.”**
   
   *Tools combined:* `netstat`, `get_process_id`, `authentic`, `tcp_probe` (with `primary_ipv4`), `banner_probe`, optionally `service_probe`
   
   *Agent analysis:* correlate PID ↔ endpoint, then test reachability via non-loopback address mode.

4) **“Port 445 is open. Validate it behaves like SMB (not HTTP/TLS), and explain what results would indicate a proxy or port-forward instead.”**
   
   *Tools combined:* `tcp_probe`, `banner_probe`, `tls_probe`, `service_probe`
   
   *Agent analysis:* interpret resets/timeouts/wrong-version errors to infer protocol mismatch vs. middleboxes.

5) **“Check whether my local TLS service on port 8443 is using a weak protocol/cipher and retrieve its certificate chain for inspection.”**
   
   *Tools combined:* `tls_probe`, `tls_cipher_sweep`, `cert_chain_probe`
   
   *Agent analysis:* identify downgrade support, weak suites, and mismatched cert chain patterns.

6) **“I suspect a local malware is running a covert listener. Find any listening ports where the owning binary is unsigned or not trusted, then verify which of those ports are reachable via primary IPv4.”**
  
   *Tools combined:* `netstat`, `tasklist`, `get_process_id`, `authentic`, `tcp_probe` (`primary_ipv4`), `banner_probe`
   
   *Agent analysis:* combine trust (signature) + network exposure to triage likely malicious listeners.

7) **“Port 9999 shows as open, but my app can’t connect. Diagnose whether it’s actually listening, whether a firewall rule blocks it, and whether it only binds to localhost.”**
   
   *Tools combined:* `tcp_probe` (both `ipv4_loopback` and `primary_ipv4`), `netstat`, `find_firewall_rules_by_port`, `firewall_settings`, optionally `service_probe`
   
   *Agent analysis:* distinguish bind-scope issues from firewall policy vs. transient listeners.

8) **“Explain why `http_probe` times out on port 8000 even though `tcp_probe` says OPEN. Determine whether the service is silent-until-spoken-to, TLS, or non-HTTP.”**
   
   *Tools combined:* `tcp_probe`, `banner_probe`, `http_probe`, `tls_probe`, `service_probe`
   
   *Agent analysis:* protocol inference from failure modes (timeouts vs resets vs wrong-version) rather than banners.

9)  **“Given a file path to an executable, tell me whether it exists, what version it is, whether it’s signed, and whether it currently owns any listening ports.”**
   
   *Tools combined:* `exist_check`, `file_version`, `authentic`, `netstat`, `tasklist`, `get_process_id`
   
   *Agent analysis:* tie software inventory to runtime exposure; detect “installed but not running” vs “running and exposed”.

10) **“Create a ‘minimal external exposure report’ for this PC: list ports reachable on primary IPv4, identify the service/process, and note which are allowed inbound on Public profile.”**
   
   *Tools combined:* `netstat`, `tcp_probe` (`primary_ipv4` across discovered ports), `banner_probe`, `service_probe`, `tasklist`, `get_process_id`, `find_firewall_rules_by_port`, `firewall_settings`

   *Agent analysis:* turns raw port lists into an “attack surface” report by validating reachability + policy, not just “LISTENING”.


Bonus\) **Run a self-diagnostic.**


## Requirements
- Python 3.9 or higher
- OpenAI API Key

## Installation

### Installing from PyPI

Once published, you can install the package directly:

```bash
pip install port-agent
```

### Installing from Source

1. Clone the repository
```bash
git clone https://github.com/brocla/port_agent.git
cd port_agent
```

2. Install the package:
```bash
pip install -e .
```

Or install the required dependencies manually:
```bash
pip install openai>=2.8.0
```

## API Key Setup

The Port Agent requires an OpenAI API key to function. You can obtain an API key from [OpenAI's platform](https://platform.openai.com/api-keys).

### Setting Up Your API Key

You have two options for providing your API key:

**Option 1: Environment Variable (Recommended)**

Set the `OPENAI_API_KEY` environment variable:

On Windows:
```bash
setx OPENAI_API_KEY "your-api-key-here"
```

On Linux/Mac:
```bash
export OPENAI_API_KEY="your-api-key-here"
```

To make it permanent on Linux/Mac, add the export command to your `~/.bashrc` or `~/.zshrc` file.

**Option 2: Direct Configuration**

The OpenAI Python client will automatically look for the API key in the environment variable. Alternatively, you can modify the code to pass the key directly (not recommended for security reasons).

## Usage

After installation and API key setup, run the agent:

If installed via pip:
```bash
port-agent
```

If running from source:
```bash
python port_agent.py
```

The agent will start an interactive REPL. Ask a question.