aussie-shield
README.md
<div align="center">
<!-- Hero Banner Graphic -->
<img src="assets/banner.svg" alt="aussie-shield banner" width="100%" />
<br/>
[](https://sasindudilshanranwadana.github.io/aussie-shield/)
[](https://github.com/sasindudilshanranwadana/aussie-shield/actions)
[](LICENSE)
[](https://python.org)
[](https://modelcontextprotocol.io)
<br/>
<p align="center">
<b>Australians lost $2.74 BILLION to scams in 2024 (ACCC Scamwatch).</b><br/>
<b>aussie-shield</b> is an autonomous, privacy-first threat intelligence engine engineered specifically for Australian residents, businesses, and AI agents.
</p>
[ **Launch Free Web Scanner** ](https://sasindudilshanranwadana.github.io/aussie-shield/) • [ **Python SDK** ](#python-sdk) • [ **Claude MCP Server** ](#claude-desktop--mcp-server) • [ **Privacy Architecture** ](#privacy-architecture) • [ **Validation Report** ](docs/VALIDATION_REPORT.md) • [ **Reporting Guide** ](docs/REPORTING_GUIDE.md)
</div>
---
## Architecture & Threat Vectors
<div align="center">
<img src="assets/architecture.svg" alt="aussie-shield Architecture & Threat Vectors" width="100%" />
</div>
---
## 30-Second Quickstart
### Option A: Use Instantly Online (Zero Installation)
Visit the public web scanner directly from any device:
**[https://sasindudilshanranwadana.github.io/aussie-shield/](https://sasindudilshanranwadana.github.io/aussie-shield/)**
### Option B: Deep Multilingual Analysis (Opt-in)
The public web app defaults to **Private Check**: message text stays in the browser and only local indicators run. Users can explicitly enable **Deep Analysis** to send up to 2,000 characters over HTTPS to the project Cloudflare Worker, where Workers AI returns a structured multilingual triage response. It is not a verification or safety guarantee.
See [`worker/README.md`](worker/README.md) for the Worker deployment, consent, rate-limit, and data-disclosure contract.
### Option C: Terminal CLI (Python / uv)
```bash
# Run instantly with uv
uvx aussie-shield check-message "Your ATO tax refund of $1,200 is pending: bit.ly/myato-secure"
# Or install via pip
pip install aussie-shield
```
---
## Core Capabilities
<table>
<tr>
<td width="50%">
<h3>Message & SMS Scam Radar</h3>
<ul>
<li><b>100% Client-Side Evaluation</b> — Zero network calls or transmission of private text.</li>
<li><b>20+ Australian Attack Models</b> — ATO refunds/debts, myGov identity phishing, AusPost delivery fees, Linkt tolls, NBN technician impersonation, gift card extortion, and crypto scams.</li>
</ul>
</td>
<td width="50%">
<h3>Multi-Feed URL Intelligence</h3>
<ul>
<li><b>Local Signals + External Feeds</b> — Local allowlist and impersonation analysis, plus Google Safe Browsing, URLScan.io, PhishTank, RDAP, and optional AbuseIPDB lookups.</li>
<li><b>Data Disclosure Is Explicit</b> — RDAP and URLScan.io receive the domain only. Google Safe Browsing v4 and PhishTank may receive the full URL when those lookups run.</li>
<li><b>RDAP Domain Age Telemetry</b> — Flags newly registered lookalike domains (<30 days old).</li>
</ul>
</td>
</tr>
<tr>
<td width="50%">
<h3>ABN & Invoice Fraud Validator</h3>
<ul>
<li><b>Mathematical Checksum</b> — Validates official ATO Mod-89 checksum algorithm locally.</li>
<li><b>Live ABR Integration</b> — Queries Australian Business Register API for live status and entity name.</li>
<li><b>Name Mismatch Detection</b> — Prevents Business Email Compromise (BEC) and fake invoice scams.</li>
</ul>
</td>
<td width="50%">
<h3>Phone Risk & E.164 Classifier</h3>
<ul>
<li><b>Premium Rate (190x) Flags</b> — Identifies high-cost per-minute callback traps.</li>
<li><b>Geographic Landline Parsing</b> — NSW/ACT (02), VIC/TAS (03), QLD (07), SA/WA/NT (08).</li>
<li><b>Spoofing Telemetry</b> — Contextual warnings on easily spoofed mobile numbers (04xx).</li>
</ul>
</td>
</tr>
</table>
---
## CLI Showcase
### 1. Evaluate Suspicious URLs
```bash
aussie-shield check-url "https://myg0v-verify.com/login"
```
```
[HIGH RISK] HIGH RISK — Domain resembles myGov (possible phishing); Domain is 3 day(s) old
URL: https://myg0v-verify.com/login
Domain: myg0v-verify.com
Domain age: 3 day(s)
Flagged by: Impersonation Rule Engine, RDAP Bootstrap
Action: Do NOT visit this URL or enter credentials.
Report: https://portal.scamwatch.gov.au/report-a-scam/
```
### 2. Check SMS / Email Texts
```bash
aussie-shield check-message "Final notice: Unpaid tax debt of $3,400 with ATO. Purchase $500 iTunes gift cards immediately or warrant will be issued."
```
```
[CRITICAL RISK] Payment demanded via gift cards (iTunes, Google Play, Steam) detected (confidence: 95%)
Matched indicators:
- gift card
- ato
- debt
- warrant
What to do:
1. No government agency, bank, or legitimate business will EVER ask for payment via gift cards
2. This is ALWAYS a scam
3. Report to Scamwatch immediately (https://portal.scamwatch.gov.au/report-a-scam/)
```
### 3. Verify Business ABN & Invoice Alignment
```bash
aussie-shield check-abn 51824753556 --name "Amazon Australia"
```
```
[ACTIVE] ABN 51 824 753 556 — [Registered Entity] (Australian Private Company) | Name: MISMATCH
ABN: 51 824 753 556
Registered Name: [Entity Name on Register]
Status: Active
GST Registered: Yes
Name Match: MISMATCH
Risk Flags:
- Name mismatch: Claimed 'Amazon Australia' but registered to '[Entity Name]'. Possible invoice redirection fraud.
```
---
## Claude Desktop / MCP Server
Integrate `aussie-shield` directly into Claude Desktop or any MCP client for autonomous scam detection during conversation:
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"aussie-shield": {
"command": "aussie-shield",
"args": ["serve"],
"env": {
"AUSSIE_SHIELD_GOOGLE_KEY": "your-google-safe-browsing-key",
"AUSSIE_SHIELD_ABR_GUID": "your-abr-guid",
"AUSSIE_SHIELD_ABUSEIPDB_KEY": "your-abuseipdb-key"
}
}
}
}
```
### Exposed MCP Tools
- `check_url(url)` — Multi-feed threat lookup + domain age
- `check_message(text)` — 20+ AU scam patterns (100% local)
- `check_abn(abn, claimed_name)` — ABR register lookup & name reconciliation
- `check_phone(number)` — Australian E.164 and 190x risk analysis
- `generate_report(...)` — Formatted Scamwatch/ReportCyber submission draft
- `get_scam_briefing(scam_type)` — Tactical response briefings
---
## Python SDK
```python
from aussie_shield.checkers.message_checker import check_message
from aussie_shield.checkers.url_checker import check_url
from aussie_shield.checkers.abn_checker import check_abn
from aussie_shield.checkers.phone_checker import check_phone
# Message scan (Zero Network)
msg_res = check_message("AusPost: Parcel held at depot. Pay $3.50 fee at bit.ly/auspost-fee")
print(msg_res.risk_level) # 'HIGH'
print(msg_res.scam_type) # 'AusPost / Delivery Fee Scam'
print(msg_res.what_to_do) # List of remediation steps
# Domain scan
url_res = check_url("https://myg0v-auth.com/login")
print(url_res.risk_level) # 'HIGH'
print(url_res.impersonation_flags) # ["Domain resembles myGov (possible phishing)"]
# ABN verification
abn_res = check_abn("51824753556", claimed_name="Amazon Australia")
print(abn_res.valid_format) # True
print(abn_res.claimed_name_match) # False (triggers invoice alert)
```
---
## Privacy Architecture
| Engine Tool | Data Sent Externally | Destination | Protocol / Privacy Safeguard |
|:---|:---|:---|:---|
| `check_message` Private Check | **None** | Local Machine Only | Default browser-only local indicators |
| `check_message` Deep Analysis | Message text after explicit consent | Cloudflare Worker / Workers AI | Optional multilingual triage; message text is not persisted by the Worker |
| `check_url` local allowlist / impersonation | **None** | Local Machine Only | Known-safe domains and brand indicators are evaluated locally |
| `check_url` Google Safe Browsing v4 / PhishTank | Full URL when the lookup runs | Third-party threat feeds | Use only where the user accepts disclosure to the selected feed |
| `check_url` RDAP / URLScan.io | Domain only | Registry / URLScan.io | Domain string only; paths and tokens are stripped |
| `check_url` AbuseIPDB | IP address only, when an IP URL is supplied | AbuseIPDB | Requires a user-provided API key |
| `check_abn` | ABN Number | ABR Public Register | Public business identifier |
| `check_phone` | **None** | Local Machine Only | 100% Offline Regex & E.164 Engine |
| `generate_report`| **None** | Local Machine Only | Markdown generated locally |
---
## Incident Response: If You Have Been Scammed
1. **Immediate Financial Freeze** — Call your financial institution's fraud hotline immediately within 24 hours to attempt transaction recall.
2. **Report to Scamwatch (ACCC / NASC)** — [portal.scamwatch.gov.au/report-a-scam](https://portal.scamwatch.gov.au/report-a-scam/)
3. **Report to ACSC ReportCyber** — [cyber.gov.au/report-and-recover/report](https://www.cyber.gov.au/report-and-recover/report) if passwords, credentials, or identity documents were compromised.
4. **National Identity Support (IDCARE)** — Call **1800 595 160** ([idcare.org](https://www.idcare.org)) for identity recovery planning.
*See the full [Incident Reporting Guide](docs/REPORTING_GUIDE.md) for direct numbers to major Australian banks (CommBank, ANZ, Westpac, NAB, ING).*
---
## Legal & Indicative Disclaimer
`aussie-shield` provides indicative risk scoring based on algorithmic pattern matching and threat intelligence feeds. It does not constitute legal, financial, or law enforcement advice.
This project is independently developed and maintained under the MIT License. It is not affiliated with, operated by, or endorsed by the Australian Government, ACCC, ACSC, or the Australian Taxation Office. See [DISCLAIMER.md](DISCLAIMER.md) for full terms.
---
<div align="center">
Engineered with precision for Australia by **[@sasindudilshanranwadana](https://github.com/sasindudilshanranwadana)**
*Master of Information Technology (Cybersecurity) · Charles Darwin University*
[](https://github.com/sasindudilshanranwadana/aussie-shield)
[](https://github.com/sasindudilshanranwadana/aussie-shield)
</div>
---
### Support & Community
If you find this project useful, you can support continuous development:
[](https://buymeacoffee.com/sasiverse)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues