PingKong

PingKong is a small, portable command-line tool that checks whether a machine can reach the hosts and services your software depends on. You describe everything in one JSON file; it runs the checks and writes a plain-text report you can archive, attach to a ticket, or compare across environments.

Typical uses

• Confirm a server can resolve DNS and reach required APIs, FTP sites, or TCP ports before a big install.
• After deployment, quickly see whether a dependency is down, blocked, or misconfigured.

---

Quick start

1. Copy the sample config and edit it for your environment:

   cp config.example.json config.json

   (config.json is ignored by Git so your secrets stay local.)

2. Run PingKong from the project folder:

   dotnet run --project PingKong -- -c config.json -o my-report.txt

   Or run the published executable the same way once you have built it (see Portable build).

3. Open my-report.txt and review DNS, connectivity, and any error details per endpoint.

---

Requirements

• .NET 8 SDK to build and run with dotnet run, or
• No runtime install needed if you publish a self-contained binary (see below).

---

Command line

PingKong [-c config.json] [-o report.txt]

Option	Meaning
-c / --config	Path to your JSON config (default: config.json in the current directory)
-o / --output	Where to write the report (default: connectivity-report-YYYYMMDD-HHmmss.txt)

---

Configuration

Start from config.example.json. Each entry under endpoints is one check.

Strategies

Strategy	What it does
ping	ICMP ping to the host (on Windows you may need an elevated shell if ping is blocked)
telnet	Opens a TCP connection (think “can I reach this port?”). Use tcp://host:port or host:port
http	Sends an HTTP request; supports GET, POST, JSON bodies, and several auth styles
ftp	Connects over FTP/FTPS and optionally verifies that listed folders exist

FTP ("strategy": "ftp")

• url: ftp://host[:port] or ftps://host[:port]. You can also set "useSsl": true with ftp:// for explicit FTPS.
• ftp block:
  • username / password — optional; if both omitted, anonymous login is used (anonymous / guest@example.com).
  • useSsl — true for FTP over TLS.
  • folders — paths from the server root (e.g. /incoming). Leading / is optional. Use an empty list to only verify you can connect and list the root.

You may put credentials in the URL (ftp://user:password@host:21), but you still need the ftp object for options like folders.

HTTP authentication

Type	Purpose
basic	username + password → Authorization: Basic
bearer	Static token → Authorization: Bearer
apikey	Custom header + value (default header name: X-API-Key)
oauth_client	Classic OAuth2 client credentials: tokenUrl, clientId, clientSecret → obtains access_token and sends it as Bearer
custom_headers	Arbitrary headers (good for APIs that expect client_id, secret, or custom JSON headers)
bearer_from_token	POST JSON to tokenUrl (tokenBody), read tokenResponseField (default access_token), then call the real URL with Bearer

HTTP method and body

Optional fields on HTTP endpoints:

• httpMethod — e.g. GET, POST (default GET)
• body — JSON object (or array/string) sent as the request body
• contentType — default application/json

---

Portable build

To produce a single folder (or single-file exe on Windows) that does not require .NET on the target machine:

dotnet publish PingKong/PingKong.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -o publish/win-x64

You will get publish/win-x64/PingKong.exe. Copy that plus your config.json to another Windows machine and run it.

For Linux or macOS, change -r to linux-x64 or osx-arm64 / osx-x64 as needed.

Tip: the publish/ folder is a good place for local configs and reports. This repo’s .gitignore excludes publish/ so those files are less likely to be committed by mistake.

---

Security and Git

• Never commit real passwords, API keys, or client secrets. The sample file uses placeholders only.
• Keep real configs as config.json (already in .gitignore) or outside the repo.
• If you ever paste a real token into a report or config by accident, rotate that credential with your provider—deleting the file does not undo someone seeing it.

---

Report contents

Each run produces a text report with:

• When and where — timestamp with timezone, machine name, and local IP (so you know which box ran the test)
• Per endpoint — DNS resolution, connectivity result, and details (status codes, errors, etc.)
• Summary — counts of DNS and connectivity successes

If something fails, the Details column is written in full so you can see the exact error message from the network stack or HTTP response.

---

Happy probing. If you extend PingKong for your team, consider keeping config.example.json updated so newcomers have a friendly reference.