Dead Man (PowerShell Edition)

Ported from upa/deadman (MIT License)

deadman is a host monitoring tool using ICMP Ping and TCP Ping. It checks whether hosts are alive via ICMP Echo or TCP SYN and displays results in real-time through a terminal UI.

This version is implemented in PowerShell 5.1+ (recommended: PowerShell 7+), using the System.Console API for terminal rendering. Works on Windows, macOS, and Linux.

Features

• 🔍 Real-time ping monitoring of multiple hosts
• 📊 Unicode bar chart display for RTT history (▁▂▃▄▅▆▇█)
• 🎨 Color-coded: green = alive, red = no response
• ⚡ Supports both sync (sequential) and async (parallel) ping modes
• � TCP ping support: Test-NetConnection on Windows, hping3 on macOS/Linux
• �📁 Configuration file format fully compatible with the original
• 📝 Optional logging functionality
• 🔄 Key interaction: r to reset statistics, q to quit
• 📐 Automatic terminal size detection and redraw

Prerequisites

• PowerShell 5.1 or later (PowerShell 7+ recommended for best experience)
  • Windows 10 / Windows Server 2016+: Windows PowerShell 5.1 is built-in
  • Windows: winget install Microsoft.PowerShell (for PowerShell 7)
  • macOS: brew install powershell
  • Linux: See official installation guide
• Async mode uses Start-ThreadJob on PowerShell 7+ or Start-Job on PowerShell 5.1
• TCP ping on macOS/Linux requires hping3 (brew install hping / apt install hping3)
• TCP ping on macOS/Linux requires sudo (root privileges) to send raw packets: sudo pwsh ./deadman.ps1 ...
• TCP ping on Windows uses the built-in Test-NetConnection cmdlet

Windows Compatibility

OS	PowerShell 5.1	PowerShell 7+
Windows Server 2019	✅	✅
Windows Server 2022	✅	✅
Windows 10	✅	✅
Windows 11	✅	✅

Terminal & Character Display

• Windows Terminal (recommended): Full Unicode bar chart support (▁▂▃▄▅▆▇█), best visual experience
• conhost (legacy console): Automatically falls back to ASCII characters (_.:‐+=@#) for RTT bar chart
• To enable Unicode in conhost, run chcp 65001 before executing the script, or use a font like Cascadia Code

Quick Start

# Clone the project
git clone https://github.com/pichuang/deadman-pwsh.git
cd deadman-pwsh

# Start with default config file (sync mode)
./deadman.ps1 -ConfigFile deadman.conf

# Async mode (ping all targets simultaneously)
./deadman.ps1 -ConfigFile deadman.conf -AsyncMode

# Custom RTT scale at 20ms with logging enabled
./deadman.ps1 -ConfigFile deadman.conf -Scale 20 -LogDir ./logs

Parameters

Parameter	Alias	Type	Description
-ConfigFile		string	Configuration file path (required)
-Scale	-s	int	RTT bar chart scale, default 10 (milliseconds)
-AsyncMode	-a	switch	Enable async ping mode
-BlinkArrow	-b	switch	Blink arrow indicator in async mode
-LogDir	-l	string	Log directory path

Configuration File Format

The configuration file format is fully compatible with the original deadman:

#
# deadman configuration file
# Format: name    address    [options]
#

# === Basic targets ===
googleDNS       8.8.8.8
quad9           9.9.9.9

# === Separator (use --- or more hyphens) ===
---

# === IPv6 targets ===
googleDNS-v6    2001:4860:4860::8888

# === Specify source interface ===
local-eth0      192.168.1.1     source=eth0

# === TCP ping targets ===
web-https       10.0.0.1        via=tcp port=443
web-http        10.0.0.2        via=tcp port=80

Supported Options

Option	Description
source=interface	Specify the source network interface for ping
via=tcp	Use TCP SYN ping instead of ICMP
port=number	TCP port number (requires via=tcp)

Note: The original advanced options such as SSH relay (relay=), SNMP (via=snmp), netns, and VRF are parsed but not used in this version. They will not produce errors.

Key Bindings

Key	Action
r	Reset all target statistics
q	Quit the program

Running Tests

Uses Pester 5 test framework:

# Install Pester (if not already installed)
Install-Module -Name Pester -MinimumVersion 5.0 -Force -Scope CurrentUser

# Run all tests
Invoke-Pester ./tests/ -Output Detailed

# Run a specific test file
Invoke-Pester ./tests/ConfigParser.Tests.ps1 -Output Detailed

# Exclude tests requiring network access
Invoke-Pester ./tests/ -Output Detailed -ExcludeTag 'Network'

Project Structure

deadman-pwsh/
├── deadman.ps1                  # Single-file program (all classes, parser, UI, and main loop)
├── deadman.conf                 # Example configuration file
├── LICENSE                      # MIT License
├── SECURITY.md                  # Security policy and vulnerability reporting
├── README.md                    # English documentation
├── README.zh-tw.md              # Chinese (Traditional) documentation
├── .github/
│   ├── CODEOWNERS               # Auto-assign reviewers
│   ├── dependabot.yml           # Automated dependency updates
│   ├── pull_request_template.md # PR checklist template
│   └── workflows/
│       ├── ci.yml               # CI tests (Windows Server 2022/2025 × PS 5.1/7)
│       ├── sast.yml             # SAST (CodeQL + PSScriptAnalyzer)
│       ├── fuzzing.yml          # Fuzz testing (property-based)
│       ├── scorecard.yml        # OpenSSF Scorecard analysis
│       ├── release.yml          # Release with SLSA provenance
│       └── pr-assign.yml        # Auto-assign PR assignee/reviewer
└── tests/
    ├── ConfigParser.Tests.ps1   # Config parser unit tests
    ├── ConsoleUI.Tests.ps1      # Console UI unit tests
    ├── PingTarget.Tests.ps1     # PingTarget unit tests
    ├── Integration.Tests.ps1    # Integration tests
    ├── WindowsCompat.Tests.ps1  # Windows compatibility tests
    └── Fuzz.Tests.ps1           # Fuzz / property-based tests

Note: deadman.ps1 is fully self-contained — just download this single file and deadman.conf to get started.

CI/CD & Security

Workflow	Purpose	Schedule
CI	Pester tests on Windows Server 2022/2025 × PS 5.1/7 (4 matrix)	Push/PR
SAST	CodeQL (Actions security) + PSScriptAnalyzer (SARIF → Code Scanning)	Push/PR + Weekly
Fuzzing	20 property-based fuzz tests (injection, Unicode, edge cases)	Push/PR + Weekly
Scorecard	OpenSSF Scorecard analysis → scorecard.dev	Push + Weekly
Release	Build zip + SHA-256 + SLSA provenance (Sigstore)	Tag push (yyyymmdd)
PR Auto-Assign	Auto-assign assignee + CODEOWNERS reviewer	PR open/reopen

Branch Protection (main)

• Require 1 PR review approval (CODEOWNERS enforced)
• Require 4 CI status checks to pass
• Dismiss stale reviews on new commits
• No force push / branch deletion
• Conversation resolution required

Releasing

Create a date-based tag to trigger a release:

git tag -a 20260419 -m "Release 20260419"
git push origin 20260419

The release workflow will:

1. Build a zip archive (deadman-pwsh-20260419.zip)
2. Generate SHA-256 checksums
3. Create SLSA provenance attestation (.sigstore.json)
4. Publish to GitHub Releases

Verify a release:

sha256sum -c checksums-sha256.txt
gh attestation verify deadman-pwsh-20260419.zip -o pichuang

Security

See SECURITY.md for vulnerability reporting policy.

Differences from Original

Feature	Original (Python)	This Version (PowerShell)
Language	Python 3 + curses	PowerShell 5.1+
UI Framework	curses	System.Console API
Ping Implementation	subprocess (ping command)	Test-Connection Cmdlet
Async	asyncio	ThreadJob (PS7+) / Start-Job (PS5.1)
SSH Relay	✅	❌ (config compatible, but not used)
SNMP Ping	✅	❌
RouterOS API	✅	❌
netns / VRF	✅	❌
TCP Ping (hping3)	✅	✅ (Windows: tnc, macOS/Linux: hping3)
SIGHUP Reload	✅	❌ (SIGHUP not supported on Windows)

License

MIT License — same as the original

Acknowledgements

• upa/deadman — Original Python version
• Original design and implementation: Interop Tokyo ShowNet NOC team