📦 Link Shield

> Link Shield is a lightweight cybersecurity-focused npm package that detects suspicious and malicious URLs using heuristics, fuzzy matching, and threat intelligence patterns.
> It helps developers, security teams, and applications identify phishing attempts, typosquatting domains, dangerous downloads, obfuscated IPs, suspicious TLDs, and other link-based threats.

---

🛡️ Why Cybersecurity Teams Need This

More than 90% of cyberattacks start with a malicious link — whether in phishing emails, social engineering messages, or compromised websites.
Attackers commonly use:

* Typosquatting domains (paypa1.com, g00gle.net)
* Free hosting/CDNs (Firebase, Dropbox, GitHub raw)
* Obfuscation tricks (punycode, encoded IPs, double extensions)
* Dangerous downloads (.exe, .apk, .scr)

Link Shield provides a simple way to detect and score these threats automatically. It can be integrated into:

* 📨 Email security filters (detect phishing links in inbound emails)
* 🌐 Web applications (protect users from malicious redirects)
* 🔍 Threat intelligence pipelines (scan large volumes of URLs)
* 🧑‍💻 DevSecOps tooling (validate links in CI/CD or monitoring scripts)

---

🚀 Features

* ✅ Detects phishing & typosquatting with fuzzy matching
* ✅ Identifies malicious protocols (javascript:, data:, file:)
* ✅ Flags suspicious TLDs (.xyz, .tk, .ru)
* ✅ Catches obfuscation tricks (punycode, Unicode homoglyphs, hex IPs)
* ✅ Detects dangerous downloads (.exe, .apk, .scr)
* ✅ Warns on free hosting/CDN abuse (Dropbox, Firebase, GitHub raw, IPFS)
* ✅ Provides a risk score (0–100) with reasons for transparency

---

📦 Installation

``bash
npm install link-shield
`

or using yarn:

`bash
yarn add link-shield
`

---

⚡ Usage

`js
const { detectSuspiciousLink } = require("link-shield");

const result = detectSuspiciousLink("http://g00gle.com/login");

console.log(result);
`

$3

`json
{
"url": "http://g00gle.com/login",
"suspicious": true,
"riskScore": 60,
"reasons": [
"Domain contains numbers (possible typosquatting)",
"Lookalike domain detected: g00gle ≈ google",
"Suspicious keyword in domain"
]
}
`

---

⚙️ API

$3

url (string, required)* → The URL to analyze
options (object, optional)*

threshold (number, default: 20)* → Minimum score to mark as suspicious

Returns:

`ts
{
url: string;
suspicious: boolean;
riskScore: number; // 0–100
reasons: string[];
}
`

---

🔐 Cybersecurity Use Cases

* Email Security → Filter malicious links in phishing campaigns
* Web Security → Block suspicious redirects or downloads before execution
* Threat Intelligence → Enrich suspicious indicators (IOCs) with scoring
* SOC Tools → Automate link triage in incident response
* CI/CD Security → Validate external links in codebases or docs

---

🧪 Testing

We use Jest for testing. Run tests with:

`bash
npm test
`

Example test case (test/detector.test.js):

`js
const { detectSuspiciousLink } = require("../src");

test("flags g00gle.com as suspicious", () => {
const result = detectSuspiciousLink("http://g00gle.com/login");
expect(result.suspicious).toBe(true);
expect(result.riskScore).toBeGreaterThan(20);
});
`

---

🔮 Roadmap

* [ ] CLI support (npx link-shield `)
* [ ] Configurable rule sets (enable/disable rules)
* [ ] Integration with threat intelligence feeds
* [ ] Browser extension integration
* [ ] Machine-learning powered URL classification