Mushie/new docs

concepts/allowlist.mdx

@@ -0,0 +1,139 @@
+---
+title: "Allowlist"
+description: "Understanding how ChainPatrol identifies and protects legitimate assets"
+---
+
+## Overview
+
+An **allowlist** is a curated list of known, trusted assets that are explicitly recognized as legitimate within ChainPatrol.
+
+<Info>
+Assets added to the allowlist are considered **official or approved** and are treated differently from unknown or suspicious assets during threat detection and analysis.
+</Info>
+
+Allowlisting helps ChainPatrol distinguish between genuine brand-owned content and potential impersonation or abuse.
+
+Unlike blocklists, which focus on malicious content, allowlists define what is **known to be safe**.
+
+## Why We Use an Allowlist at ChainPatrol
+
+Allowlists play a critical role in improving both **detection accuracy** and **signal quality**.
+
+### Dual Purpose
+
+**Exclusion from Detection** - When an asset is allowlisted, it is excluded from automatic threat detection. This prevents legitimate brand-owned assets from being mistakenly flagged as impersonation, reduces false positives, eliminates unnecessary investigations, and improves team efficiency. For example, your official website `example.com` is allowlisted, so it will never be flagged as a phishing site, even if detection rules would normally trigger on brand-related keywords.
+
+**Reference Baseline** - Allowlisted assets are used as reference points when analyzing potentially malicious content. ChainPatrol can compare a suspected phishing page against an allowlisted official website to determine whether branding is being copied, layout is being imitated, content is being duplicated, and visual elements are being stolen. For example, a suspicious site `examp1e.com` is detected. ChainPatrol compares it against your allowlisted `example.com` and identifies 95% visual similarity, identical logo usage, and copied page structure, resulting in high-confidence brand impersonation detection.
+
+This dual role (exclusion from detection and use as a trusted baseline) makes allowlists essential for reliable brand impersonation analysis.
+
+## What Can Be Allowlisted?
+
+In ChainPatrol, **any asset type can be allowlisted**:
+
+- **Domains and URLs** - Official websites and web applications
+- **Social Media Accounts** - Verified brand and employee accounts
+- **Application Pages** - App store listings and hosted content
+- **Development Environments** - Testing, staging, and QA environments
+- **Preview Deployments** - Vercel, Netlify, and other preview URLs
+- **Blockchain Addresses** - Official smart contracts and wallets
+- **Email Addresses** - Official company and team emails
+- **Other Assets** - Any asset legitimately controlled by your organization
+
+Allowlisting is not limited by platform or asset category, as long as the asset is known to be legitimately controlled by the organization or brand.
+
+## What Should and Shouldn't Be Allowlisted?
+
+### Should Be Allowlisted ✅
+
+Assets that are **owned, controlled, or intentionally operated** by the organization or its brands:
+
+**Official Websites** - Primary company website, product websites, documentation sites, support portals, marketing landing pages. Example: `company.com`, `docs.company.com`, `support.company.com`
+
+**Verified Social Media Accounts** - Official Twitter/X accounts, official Discord servers, official Telegram channels, official YouTube channels, verified employee accounts. Example: `@CompanyOfficial`, `discord.gg/company-official`
+
+**Internal Testing Environments** - QA environments, staging servers, internal testing sites, employee development environments. Example: `staging.company.com`, `qa-env.company.com`
+
+**Development and Preview Pages** - Vercel deployments owned by the company, Netlify preview URLs, GitHub Pages for official repositories, CI/CD preview environments. Example: `company-app.vercel.app`, `preview-123.netlify.app`
+
+**Official Blockchain Assets** - Official smart contracts, treasury wallets, multisig addresses, token contracts. Example: `0x1234...` (official token contract)
+
+### Should NOT Be Allowlisted ❌
+
+**Third-Party Content** - Content that is merely tolerated but not controlled by your organization, including partner websites mentioning your brand, news articles about your company, third-party reviews or comparisons, and affiliate or reseller sites. Even if the content is positive or authorized, if you don't control it, don't allowlist it.
+
+**User-Generated Content** - Content created by users, even on your platforms, including user profiles on your platform, community-submitted content, user comments or posts, and customer testimonials on external sites.
+
+**Assets Not Fully Controlled** - Assets where you don't have complete control or ownership, including shared hosting environments, third-party integrations, external widgets or embeds, and temporary or borrowed infrastructure. If there's any doubt about control or ownership, err on the side of caution and don't allowlist.
+
+<Warning>
+**Important:** Allowlisting an asset implicitly signals trust. Because allowlisted assets are excluded from automatic detection, incorrectly allowlisting an asset can reduce visibility into real threats.
+</Warning>
+
+## Risk Handling and Escalation
+
+Allowlisting does not permanently exempt an asset from scrutiny.
+
+If an allowlisted asset shows suspicious behavior or is believed to be compromised, it can still be escalated, investigated, and acted upon.
+
+### Compromise Scenarios
+
+**Account Compromise** - If your official Twitter account is hacked: Asset is allowlisted so automatic detection doesn't flag it, community reports suspicious activity, manual investigation reveals compromise, asset is temporarily removed from allowlist, threat is blocked and reported, after recovery asset is re-allowlisted.
+
+**Domain Hijacking** - If your domain is hijacked or DNS is compromised: Asset is allowlisted so automatic detection doesn't flag it, monitoring detects unusual behavior or content changes, security team investigates, asset is removed from allowlist during incident, malicious content is blocked, after resolution asset is re-allowlisted.
+
+**Infrastructure Breach** - If your hosting infrastructure is compromised: Allowlisted assets start serving malicious content, user reports or automated monitoring detect anomalies, incident response is triggered, affected assets are removed from allowlist, threats are contained and remediated, assets are re-allowlisted after verification.
+
+This ensures that trust is not absolute and that compromised official assets do not become blind spots.
+
+## Granularity of Allowlists
+
+Allowlists in ChainPatrol can be configured at different levels:
+
+**Organization Level** - Assets allowlisted at the organization level are trusted for the entire organization, regardless of which brand they're associated with. Use cases include corporate websites, shared infrastructure, company-wide social accounts, and central authentication systems. Example: `company.com` is allowlisted at the organization level, protecting it for all brands under the organization.
+
+**Brand Level** - Assets allowlisted at the brand level are trusted only for that specific brand within the organization. Use cases include product-specific websites, brand-specific social accounts, individual product infrastructure, and brand-specific campaigns. Example: `product-a.com` is allowlisted for "Product A" brand but not for "Product B" brand.
+
+This flexibility allows teams managing multiple brands to tailor trust appropriately.
+
+### Hierarchy Example
+
+```
+Organization: Acme Corp
+├── Brand: Acme Protocol
+│   ├── acme-protocol.com (Brand-level allowlist)
+│   └── @AcmeProtocol (Brand-level allowlist)
+├── Brand: Acme Wallet
+│   ├── acme-wallet.com (Brand-level allowlist)
+│   └── @AcmeWallet (Brand-level allowlist)
+└── Organization-level allowlist:
+    ├── acme.com (All brands)
+    ├── @AcmeCorp (All brands)
+    └── support@acme.com (All brands)
+```
+
+## Who Can Update the Allowlist?
+
+Allowlist management is restricted to **organization administrators and authorized staff members**.
+
+- **Organization Administrators** - Full control over organization-level and brand-level allowlists
+- **Authorized Staff** - ChainPatrol staff can assist with allowlist management
+- **Limited Access** - Standard users cannot modify allowlists
+- **Audit Trail** - All allowlist changes are logged and tracked
+
+Limiting access helps ensure that allowlists remain accurate, intentional, and aligned with security best practices.
+
+### Best Practices for Allowlist Management
+
+1. **Be Conservative** - Only allowlist assets you definitively control and trust
+2. **Regular Reviews** - Periodically review your allowlist (quarterly recommended) to remove outdated or deprecated assets
+3. **Document Decisions** - Maintain internal documentation of why assets were allowlisted
+4. **Remove Compromised Assets** - Immediately remove any asset suspected of being compromised
+5. **Re-add After Verification** - Only re-allowlist assets after confirming they're secure and under your control
+
+## Key Takeaways
+
+- Allowlisting reduces false positive noise: Adding your official assets filters them from detection sources, letting your team focus review time on actual threats
+- Conservative allowlisting prevents blind spots: Only add assets you definitively control because allowlisted assets that get compromised won't trigger automatic alerts
+- Domain allowlisting uses smart matching: Adding `example.com` automatically trusts all subdomains, reducing maintenance while maintaining protection
+- Allowlist changes require administrator privileges: This restriction prevents accidental or malicious allowlisting that could create security gaps

concepts/asset-scans.mdx

@@ -0,0 +1,135 @@
+---
+title: "Asset Scans"
+description: "Understanding how ChainPatrol evaluates assets at specific points in time"
+---
+
+## Overview
+
+<Info>
+An **asset scan** is a single security check ChainPatrol performs on an asset (like a URL, social profile, app listing, crypto address, or email) at a specific moment in time.
+</Info>
+
+### What It Captures
+
+- **What We Saw** - Visual and content snapshot
+- **Extra Context** - Enrichment data collected
+- **Risk Conclusion** - Risk assessment and scores
+
+### Why It Matters
+
+Asset scans are the building blocks ChainPatrol uses to understand threats over time, update asset status, support reviews and takedowns, and power reporting and analytics.
+
+## Key Characteristics
+
+### Tied to Specific Asset
+
+Every asset scan belongs to exactly one asset and, through that asset, to an organization and optionally a brand.
+
+```
+Organization
+  └── Brand (optional)
+      └── Asset
+          └── Asset Scan
+```
+
+### Time-Bound Snapshot
+
+Each scan has a timestamp and stands on its own. Later scans might see different content, liveness status, risk indicators, and infrastructure. This allows ChainPatrol to track how threats evolve over time.
+
+### Status Tracking
+
+A scan has a simple status reflecting where it is in the checking process:
+
+1. **Pending** - Scan queued but not yet started
+2. **In Progress** - Actively collecting data and running checks
+3. **Completed** - Scan finished successfully with results
+4. **Failed** - Scan encountered errors and couldn't complete
+
+### Contents
+
+**Inputs:** What we were asked to scan (URL, address, profile) and related context (organization, brand, detection source).
+
+**Outputs:** Enrichments (extra data we fetched), labels (risk tags), liveness status, and overall risk score for that point in time.
+
+## What Lives Inside a Scan
+
+### Enrichments (Extra Context)
+
+Structured information gathered during the scan:
+
+**Web Content & Metadata** - Page HTML and text content, title, description, keywords, meta tags and structured data, screenshots and visual captures, form fields and input elements.
+
+**Links Discovered** - Outbound links from the page, redirect chains, external resources loaded, related infrastructure.
+
+**Technical Details** - DNS records and resolution, TLS/SSL certificate information, IP addresses and hosting, server headers and responses, network infrastructure.
+
+**Platform-Specific Details** - Social profile attributes (followers, posts, bio), app store listing information (ratings, reviews, permissions), blockchain data (contract code, transactions), email validation results.
+
+Each enrichment knows where it came from (e.g., "page content", "network", or an external scanner) and whether it succeeded or failed.
+
+### Labels (Findings)
+
+Human-readable tags with scores that categorize risk:
+
+- **Brand Impersonation** - Visual or textual mimicry of your brand
+- **General Phishing** - Credential harvesting or scam patterns
+- **Provider Blocked** - Suspended or blocked by hosting provider
+- **Wallet Drainer** - Malicious wallet connection code
+- **Parked Domain** - Domain reserved but not in use
+- **Typosquatting** - Domain closely resembling legitimate one
+
+These labels are used to group risk into categories like general phishing, brand impersonation, or wallet-related risk.
+
+### Scores and Liveness
+
+A scan tracks two key metrics:
+
+**Risk Score** - A numerical score (typically 0-1) representing the overall risk level at that point in time. Calculated from label scores, rule evaluations, confidence levels, and historical patterns.
+
+**Liveness Status** - Indicates whether the asset is currently accessible:
+- **ALIVE** - Asset is accessible and active
+- **DEAD** - Asset is inaccessible or removed
+- **UNKNOWN** - Status cannot be determined
+
+Reasons tracked include DNS failed, parked domain detected, suspended by provider, 404 not found, and connection timeout.
+
+## How Asset Scans Relate to Other Concepts
+
+**Asset** - The asset is the "thing" (URL, profile, listing, address); scans are the history of what we have seen about that thing. One asset has many scans over time, and scans build a timeline of the asset's behavior. The most recent scan is typically used for current status.
+
+**Threats / Detections** - Threat records (detections) use scan labels and scores as key inputs to decide whether something should be treated as an active threat for your organization.
+
+**Reviews** - When your team reviews a reported asset, they see the most relevant scan results including screenshots, labels and scores, enrichment data, and historical scan timeline to understand why it was flagged and whether it should be allowed, blocked, or escalated.
+
+**Blocklist, Allowlist, Watchlist** - Repeated scan results help decide status: Blocked (assets that consistently look malicious), Allowed (assets that can be treated as safe), and Watchlisted (assets that are sensitive or change frequently).
+
+**Takedowns** - For assets that need to be taken down, scan data provides evidence including screenshots showing malicious content, metadata and technical details, liveness history, and timeline of activity to support outreach to hosting providers, registrars, and platforms.
+
+**Relationships Between Assets** - When scans find links and redirects, they can be connected together to show clusters of related pages or infrastructure, helping identify broader campaigns, map attacker infrastructure, understand threat networks, and coordinate takedowns.
+
+## Examples
+
+### Example 1: Suspicious Login Page
+
+A new login page is found in search results. ChainPatrol scans the page, sees it closely imitates your brand, detects wallet connection requests, and assigns strong phishing and brand-impersonation labels. The scan feeds into a threat record for your organization and appears in your triage queue with high-priority review recommended. High-confidence scans like this often trigger automatic blocking.
+
+### Example 2: Official Site Staying Healthy
+
+Your official website is added as an asset and monitored. Regular scans (daily or weekly) show the asset is alive and consistent, does not trigger risky labels, and maintains a stable risk score near zero. It remains allowed and serves as a "known good" reference used for comparison against suspicious assets.
+
+### Example 3: Impersonating Social Profile
+
+A social profile claiming to be one of your employees is discovered. The profile is scanned for attributes, shows overlapping branding, detects suspicious outreach behavior, and increases impersonation scores. The scan supports team decision-making, provides evidence for escalation, and forms the basis for pursuing takedown with documented proof of impersonation.
+
+## What Asset Scans Are Not
+
+- **Not a Human Report** - Asset scans are system-generated. Reports are created by users or external systems raising issues.
+- **Not a Case** - A scan can be clean or suspicious. A threat or incident record is created only when risk crosses thresholds or a human escalates it.
+- **Not a Configuration** - Scans use your rules, thresholds, and service settings, but they are not where you configure behavior. They are the evidence those settings produce.
+
+## Key Takeaways
+
+- One asset, many scans creates a timeline: Scanning the same URL multiple times shows how threats evolve, when they go live, and when takedowns succeed
+- Selective enrichment balances speed and depth: Basic scans are fast, but when risk signals appear, deeper analysis triggers automatically to gather decisive evidence
+- Liveness tracking enables automated workflows: Knowing when assets change from ALIVE to DEAD lets watchlist monitoring confirm takedown success without manual checking
+- Relationship extraction reveals campaigns: Links and redirects discovered during scans help trace entire threat networks instead of treating each malicious site as isolated