port-agent 0.1.1

An AI agent that diagnoses vulnerabilities in network ports using OpenAI's Responses API

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:

pip install port-agent

Installing from Source

1. Clone the repository

git clone https://github.com/brocla/port_agent.git
cd port_agent

2. Install the package:

pip install -e .

Or install the required dependencies manually:

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.

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:

setx OPENAI_API_KEY "your-api-key-here"

On Linux/Mac:

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:

port-agent

If running from source:

python port_agent.py

The agent will start an interactive REPL. Ask a question.