link-shield/README.md

Link Shield is a lightweight cybersecurity-focused npm package that detects suspicious and malicious URLs using heuristics, fuzzy matching, and threat intelligence patterns.

# 📦 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);
```

### Example Output

```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

### `detectSuspiciousLink(url, options)`

* **`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 <url>`)
* [ ] Configurable rule sets (enable/disable rules)
* [ ] Integration with **threat intelligence feeds**
* [ ] Browser extension integration
* [ ] Machine-learning powered URL classification