What Does This Tool Do?
pg_hba_analyze reads the active authentication rules from pg_hba_file_rules (PostgreSQL 15+) and evaluates each rule for security gaps. The tool detects trust authentication (no password required), overly broad network ranges (0.0.0.0/0), missing SSL enforcement, and other problematic configurations. Each rule is scored, and the overall result is summarized as a score from 0 to 100.
How Is It Called?
Step 1: Establish Multi-DB Connection
Before calling pg_hba_analyze, a database connection must exist. The MCP server supports multiple simultaneous connections:
▶ Calling tools...
→ pg_connect { "host": "localhost", "port": 5432, "database": "mcp_test", "user": "mcp_test" }
Connection established:
Status: connected
Server: PostgreSQL 17.4
Database: mcp_test
User: mcp_test
Step 2: Claude CLI (Natural Language)
▶ Calling tools...
→ pg_hba_analyze {}
pg_hba.conf analysis — 7 rules checked
Total: 7 rules
Trust rules: 6
MD5 rules: 0
Wide ranges: 1
FINDING 6 rule(s) use 'trust' authentication (no password required)
FINDING 1 rule(s) allow connections from any IP address
Line 117: local all all trust
Line 119: host all all 127.0.0.1 trust
Line 121: host all all ::1 trust
Line 124: local replication all trust
Line 125: host replication all 127.0.0.1 trust
Line 126: host replication all ::1 trust
Line 128: host all all 0.0.0.0/0 scram-sha-256
MCP Protocol (Programmatic)
The following output is from a real test run against PostgreSQL 17.4 with a default pg_hba.conf:
const result = await client.callTool("pg_hba_analyze", {});
// Response:
{
"total_rules": 7,
"trust_rules": 6,
"md5_rules": 0,
"wide_range_rules": 1,
"error_rules": 0,
"findings": [
"6 rule(s) use 'trust' authentication (no password required)",
"1 rule(s) allow connections from any IP address"
],
"rules": [
{ "line_number": 117, "type": "local", "database": ["all"], "user_name": ["all"], "address": null, "auth_method": "trust" },
{ "line_number": 119, "type": "host", "database": ["all"], "user_name": ["all"], "address": "127.0.0.1", "auth_method": "trust" },
{ "line_number": 121, "type": "host", "database": ["all"], "user_name": ["all"], "address": "::1", "auth_method": "trust" },
{ "line_number": 124, "type": "local", "database": ["replication"], "user_name": ["all"], "address": null, "auth_method": "trust" },
{ "line_number": 125, "type": "host", "database": ["replication"], "user_name": ["all"], "address": "127.0.0.1", "auth_method": "trust" },
{ "line_number": 126, "type": "host", "database": ["replication"], "user_name": ["all"], "address": "::1", "auth_method": "trust" },
{ "line_number": 128, "type": "host", "database": ["all"], "user_name": ["all"], "address": "0.0.0.0/0", "auth_method": "scram-sha-256" }
]
}
What Happens Under the Hood?
The tool reads active HBA rules via the pg_hba_file_rules system view (available since PostgreSQL 15):
SELECT line_number, type, database, user_name, address, netmask, auth_method, options, error FROM pg_hba_file_rules WHERE error IS NULL ORDER BY line_number;
Each rule is evaluated against these criteria:
- Trust Auth — Deduction of 30 points. No password required, the most severe risk.
- 0.0.0.0/0 or ::/0 — Deduction of 20 points. Allows connections from any IP address worldwide.
- No SSL — Deduction of 15 points.
hostinstead ofhostsslfor network connections means unencrypted traffic. - Peer Auth over Network — Deduction of 10 points. Peer authentication only works locally — over the network it's a configuration error.
Scoring Scale: 100 = perfect configuration, no findings. Below 70 requires urgent attention. Below 50 means the database is likely vulnerable to attack.
Output in Detail
- total_rules — Number of HBA rules analyzed
- trust_rules — Count of rules using
trustauthentication (no password) - md5_rules — Count of rules using the deprecated
md5method - wide_range_rules — Count of rules allowing connections from any IP
- error_rules — Count of malformed rules in pg_hba.conf
- findings — Array of summary strings describing detected problems
- rules — Array with each rule in detail:
- line_number — Line number in pg_hba.conf
- type —
local,host, orhostssl - database — Target database(s)
- user_name — Affected users
- address — Source IP or CIDR range
- auth_method — Authentication method
What Does the Test Suite Validate?
The test suite validates pg_hba_analyze against a PostgreSQL 17.4 instance with a default pg_hba.conf (6 trust rules + 1 scram-sha-256 rule):
✓ pg_hba_analyze > scores rules and computes total score
✓ pg_hba_analyze > detects trust authentication as critical
Test Files 1 passed (1)
Tests 3 passed (3)
Duration 287ms
Test Data Scenario (Real Data)
The test environment includes a PostgreSQL 17.4 instance with a default pg_hba.conf — 7 rules, 6 using trust auth:
- Line 117:
local all all trust— Trust auth for all local connections - Line 119:
host all all 127.0.0.1 trust— Trust auth for IPv4 localhost - Line 121:
host all all ::1 trust— Trust auth for IPv6 localhost - Lines 124-126:
replication all trust— Trust auth for all replication connections - Line 128:
host all all 0.0.0.0/0 scram-sha-256— Open CIDR, but with secure auth method
Tests validate that:
- The result contains a findings array with summaries of detected problems
- Counters are correct:
trust_rules: 6,wide_range_rules: 1 - Trust authentication is reliably detected and reported as a finding
Summary
pg_hba_analyze makes the often-neglected pg_hba.conf transparent and measurable. Instead of manually reviewing line by line, the tool delivers a score and a prioritized list of actions.
Combined with pg_vault_connect (→ dynamic credentials) and pg_permission_audit (→ GRANT analysis), it forms the core of the /pg-security workflow skill.