phisherslapper/docs/overview.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>phisherslapper Developer Docs - Overview</title>
</head>
<body bgcolor="#002b36" text="#a3b8b9" link="#859900" vlink="#b58900">
<font color="#b58900"><h1>phisherslapper [v1.03]</h1></font>
<p>Domain Impersonation and OSINT Triage Tool. Compares a known-legitimate
domain (target) against a suspect domain using DNS resolution, X.509 TLS
certificates, and RDAP registration data, then produces a deterministic risk
score and verdict. Single static binary; standard library plus
<tt>golang.org/x/sync</tt> only.</p>

<font color="#859900"><h2>Build and Run</h2></font>
<table border="0" cellpadding="8" width="100%"><tr><td bgcolor="#073642"><pre>git clone https://github.com/MARKMENTAL/phisherslapper.git
cd phisherslapper
CGO_ENABLED=0 go build -ldflags="-s -w" -o phisherslapper ./cmd/phisherslapper
./phisherslapper jdsoft.com jdsoftcareers.com
go test ./...</pre></td></tr></table>

<font color="#859900"><h2>Flags</h2></font>
<table border="1" cellpadding="4">
<tr><th>Flag</th><th>Description</th></tr>
<tr><td><tt>-v, --verbose</tt></td><td>Append raw cert policy OIDs, TLS details, and RDAP JSON.</td></tr>
<tr><td><tt>-j, --json</tt></td><td>Output the result summary as JSON for scripting.</td></tr>
<tr><td><tt>-k, --insecure</tt></td><td>Skip TLS verification for RDAP (weakens results; last resort for devices without CA certificates).</td></tr>
<tr><td><tt>--timeout=DUR</tt></td><td>Per-call deadline for DNS/TLS/RDAP; Go duration, default 5s.</td></tr>
<tr><td><tt>--scale</tt></td><td>Print the scoring scale table and exit.</td></tr>
<tr><td><tt>-h, --help</tt></td><td>Display usage and exit.</td></tr>
</table>

<font color="#859900"><h2>Fetch Pipeline</h2></font>
<p>Both domains are fetched concurrently with
<tt>golang.org/x/sync/errgroup</tt> under a 15 second global deadline; each
DNS, TLS, and RDAP call carries a 5 second deadline (adjustable with
<tt>--timeout</tt>) and is retried up to 3 times. Total run time equals the
slower of the two domains. Fail-closed errors name the underlying
cause(s).</p>
<table border="0" cellpadding="8" width="100%"><tr><td bgcolor="#073642"><pre>parse args --&gt; DNS pre-flight (target + suspect, parallel; keeps per-path IPs, checks hosts file)
            --&gt; fetch target   = RDAP + TLS + per-path TLS + ASN in parallel
            --&gt; fetch suspect  = RDAP + TLS + per-path TLS + ASN in parallel
            --&gt; sender authority = target SPF for suspect IP + target DMARC (fail-open)
            --&gt; fail-closed verify --&gt; score --&gt; render</pre></td></tr></table>
<p>Exit codes: <tt>0</tt> on success (including <tt>--scale</tt> and
<tt>--help</tt>), <tt>1</tt> on bad flags, invalid domains, DNS failure, or
failed data-quality verification.</p>

<font color="#859900"><h2>DNS Consistency</h2></font>
<p>Each domain is probed once by the system resolver plus pinned 1.1.1.1 and
8.8.8.8 servers, and the outcomes are reused downstream. Only state is
compared, never raw addresses: system-dark/public-live suppression splits
and NS delegation splits flag tampering (+50 on the suspect), while
system-live/public-dark split-horizon shapes and target-side splits stay
display-only NOTEs. CDN/GeoDNS address churn stays quiet. Inconclusive
resolvers abstain; filtered resolvers are excluded by design. The
pre-flight gate aborts on system failure with hijack-aware messaging.</p>

<font color="#859900"><h2>Rogue Redirection</h2></font>
<p>Beyond state comparison, the first live A record per side is retained and
each endpoint is interrogated: the TLS identity served at the
system-resolved IP is compared against the public-resolved IP (issuer,
validation class, SANs, leaf fingerprint; SNI preserved). Origin
autonomous systems for both IPs are attributed via Team Cymru
(<tt>origin.asn.cymru.com</tt> TXT through the pinned resolver), and the OS
hosts file is checked for static overrides. Divergent per-path TLS (+50),
split origin AS (+30), and hosts-file overrides (+50) score on the suspect;
target-side and inconclusive probes stay display-only. Raw addresses are
never compared, so CDN/GeoDNS fronting stays quiet. Max total is 330.</p>

<font color="#859900"><h2>Embedded Systems</h2></font>
<p>The tool runs on embedded ARM devices (verified on a Miyoo Mini Plus),
but minimal firmware often ships without a CA certificate store. DNS and
certificate inspection still work there, while verified HTTPS (RDAP) fails;
the fail-closed error names the cause (<tt>x509: certificate signed by
unknown authority</tt>). Install <tt>ca-certificates</tt> and fix the clock
where possible, otherwise use <tt>-k/--insecure</tt> as a last resort.</p>

<font color="#859900"><h2>Scoring Scale</h2></font>
<table border="1" cellpadding="4">
<tr><th>Signal</th><th>Points</th></tr>
<tr><td>Suspect &lt; 30d (CRITICAL), stacked w/ signal</td><td>+80</td></tr>
<tr><td>Suspect &lt; 30d (CRITICAL), isolated</td><td>+40</td></tr>
<tr><td>Suspect 30-89d (WARNING), stacked w/ signal</td><td>+40</td></tr>
<tr><td>Suspect 30-89d (WARNING), isolated</td><td>+20</td></tr>
<tr><td>Shared cert infrastructure (halves age tier)</td><td>x0.5</td></tr>
<tr><td>SPF endorsement (halves age tier)</td><td>x0.5</td></tr>
<tr><td>Identical target/suspect (forced LEGITIMATE)</td><td>+0</td></tr>
<tr><td>Resolution tampering: suppression split (suspect)</td><td>+50</td></tr>
<tr><td>DNS split-horizon / target-side (display only)</td><td>+0</td></tr>
<tr><td>Cert downgrade: target EV/OV vs suspect DV</td><td>+40</td></tr>
<tr><td>Registrar mismatch</td><td>+30</td></tr>
<tr><td>Same-class issuer difference (display only)</td><td>+0</td></tr>
<tr><td>Rogue TLS: per-path cert divergence (suspect)</td><td>+50</td></tr>
<tr><td>Rogue ASN: per-path AS split (suspect)</td><td>+30</td></tr>
<tr><td>Hosts-file override (suspect)</td><td>+50</td></tr>
<tr><td>Rogue signals target-side/inconclusive (info)</td><td>+0</td></tr>
<tr><td>Chronology inversion: suspect far older than young target (info)</td><td>+0</td></tr>
</table>
<br>
<table border="1" cellpadding="4">
<tr><th>Score</th><th>Verdict</th></tr>
<tr><td>0-14</td><td>LIKELY LEGITIMATE (related pair)</td></tr>
<tr><td>15-39</td><td>LIKELY MALICIOUS OR NEGLIGENT (related pair)</td></tr>
<tr><td>40-50</td><td>SUSPICIOUS - MANUAL REVIEW RECOMMENDED</td></tr>
<tr><td>51+</td><td>LIKELY PHISHING / IMPERSONATION ATTEMPT</td></tr>
<tr><td>0-39*</td><td>UNRELATED - NO AUTHORITY OVER TARGET</td></tr>
</table>
<p>* Unrelated pair: no shared SANs, SPF coverage, or label similarity.
LEGITIMATE requires a relationship (endorsed or lookalike). Two clean
companies sharing nothing still means zero cross-domain authority, so the
verdict never reads legitimate for them.</p>

<font color="#859900"><h2>Relationship &amp; Sender Authority</h2></font>
<p>Every pair is classified as identical, SAN-endorsed, SPF-endorsed,
lookalike (confusable-aware root-label similarity), or unrelated. The
target's SPF record is evaluated for the suspect's IP (RFC 7208 subset
through the pinned resolver, 10-lookup budget, fail-open) and the
target's DMARC policy is shown as context. Absence from SANs/SPF is never
scored — it only proves no authority, which the UNRELATED verdict
states.</p>

<font color="#859900"><h2>Packages</h2></font>
<ul>
<li><a href="dns.html"><b>dns</b></a> - normalization, syntax checks, DNS pre-flight, hosts overrides, origin-AS attribution, SPF/DMARC sender authority.</li>
<li><a href="cert.html"><b>cert</b></a> - TLS leaf fetch, validation-level classification, per-path identity comparison.</li>
<li><a href="rdap.html"><b>rdap</b></a> - RDAP client, creation date and registrar extraction.</li>
<li><a href="score.html"><b>score</b></a> - risk scoring and verdict mapping.</li>
<li><a href="report.html"><b>report</b></a> - human, JSON, scale, and verbose renderers.</li>
<li><a href="main.html"><b>main</b></a> - CLI entry point and fetch orchestration.</li>
</ul>
<hr>
<font color="#b58900">Licensed under the GNU General Public License v3 - Mark Robillard Jr (MARKMENTAL)</font>
</body>
</html>