Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -131,3 +131,24 @@ ISMALICIOUS_KEY=
# (e.g. a Discord bot on your private network).
# GITHUB_WEBHOOK_SECRET=
# GITHUB_WEBHOOK_FORWARD_URL=http://<bot-host>:<port>/github/webhook

# RECON scanner access (OWASP A01). /api/scanner makes this server probe
# arbitrary public hosts, so production builds refuse remote callers (403)
# unless one of these is set. `npm run dev` / `npm run osiris` on localhost
# works without either.
# SCANNER_ACCESS_TOKEN — shared secret for trusted users; the RECON panel
# prompts for it once per browser tab (sessionStorage) and sends it as the
# X-Scanner-Token header. Generate with: openssl rand -hex 32
# SCANNER_ALLOW_ANONYMOUS=true — let ANY visitor run scans. Not recommended:
# your server becomes a public scan relay that targets see as your IP.
# SCANNER_ACCESS_TOKEN=
# SCANNER_ALLOW_ANONYMOUS=false

# Client-IP trust for rate limits + audit log. Next.js passes a client-sent
# X-Forwarded-For through unchanged, so forwarding headers are ignored (all
# clients share one rate-limit bucket) unless you run behind a proxy that
# sets them AND the app port is reachable only through that proxy:
# true one proxy (e.g. the bundled nginx): rightmost X-Forwarded-For
# <N> N proxies in a chain: Nth X-Forwarded-For entry from the right
# cloudflare use CF-Connecting-IP (origin must accept only Cloudflare IPs)
# TRUST_PROXY_HEADERS=
19 changes: 19 additions & 0 deletions DOCKER.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,10 +137,29 @@ Copy `.env.template` to `.env` and fill in only what you need.
|----------|---------|--------------|
| `SCANNER_URL` | RECON scanner backend base URL (e.g. `http://scanner:7700`) | RECON toolkit (quick/ssl/headers/rdns/subdomains/tech/whois/geoloc/vuln) |
| `SCANNER_KEY` | Shared secret; **must equal the backend's `OSIRIS_KEY`** | RECON toolkit |
| `SCANNER_ACCESS_TOKEN` | Token trusted users enter in the RECON panel (sent as `X-Scanner-Token`) | RECON toolkit on any production/Docker deployment |
| `SCANNER_ALLOW_ANONYMOUS` | `true` lets **any** visitor run scans (not recommended) | Public scanner, deliberately |
| `TRUST_PROXY_HEADERS` | `true` / `<N>` / `cloudflare` — honour forwarding headers for client IP | Per-client rate limits behind a reverse proxy |

Without `SCANNER_URL`/`SCANNER_KEY` the RECON endpoints return `503` and the
rest of OSIRIS works normally. Generate a key with `openssl rand -hex 32`.

**Scanner access (closed by default).** The scanner makes your server probe
arbitrary public hosts, so a production build — including this Docker image —
answers `403` to RECON scans unless you set `SCANNER_ACCESS_TOKEN` (the RECON
panel prompts for it once per browser tab) or, deliberately,
`SCANNER_ALLOW_ANONYMOUS=true`. Only `npm run dev` on localhost works without
either. *Upgrading:* if you used the RECON panel on a Docker/public host, set
`SCANNER_ACCESS_TOKEN` or it stops working.

**Client IP behind nginx.** Next.js forwards a client-supplied
`X-Forwarded-For` unchanged, so OSIRIS ignores forwarding headers by default
(all clients then share one rate-limit bucket). Behind the bundled nginx, set
`TRUST_PROXY_HEADERS=true` — OSIRIS then uses the rightmost `X-Forwarded-For`
entry, which nginx appends from the real socket address. Only do this if the
app port (`OSIRIS_PORT`, 3000) is not reachable except through the proxy;
otherwise clients can connect directly and forge the header.

### Optional keys (reserved / for higher rate limits)

These are documented for completeness and forward-compatibility. The current
Expand Down
11 changes: 10 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -340,6 +340,12 @@ Place the `osiris-scanner` sidecar as a sibling folder, then:
npm run osiris # starts scanner (:7700) + dashboard (:3000)
```

The dev server allows RECON scans from `localhost` with no extra setup. A
production build (`npm start`, Docker, any public host) refuses them until you
set `SCANNER_ACCESS_TOKEN` (the RECON panel prompts for it once per tab) or,
not recommended, `SCANNER_ALLOW_ANONYMOUS=true`. See
[DOCKER.md](DOCKER.md#3-api-keys--data-sources).

Build for production:

```bash
Expand All @@ -356,6 +362,8 @@ npm run build && npm start
|----------|---------|--------|
| `GEMINI_API_KEY_1..8` | AI Intelligence Analyst (Gemini 2.5 Flash + web search) | [Google AI Studio](https://aistudio.google.com/apikey) (free) |
| `SCANNER_URL`, `SCANNER_KEY` | RECON toolkit (port scan, SSL, DNS, WHOIS, vuln) | Generate a key, match in `osiris-scanner` sidecar |
| `SCANNER_ACCESS_TOKEN` / `SCANNER_ALLOW_ANONYMOUS` | RECON scans on production/public hosts (closed by default) | `openssl rand -hex 32`; give the token to trusted users |
| `TRUST_PROXY_HEADERS` | Per-client rate limits behind a reverse proxy (`true`, hop count, or `cloudflare`) | Set only when the app port is reachable solely via the proxy |
| `URLHAUS_KEY` | URLhaus malware lookups | [abuse.ch auth](https://auth.abuse.ch/) (free) |
| `ISMALICIOUS_KEY`, `ISMALICIOUS_SECRET` | IsMalicious threat lookups (auth = base64 key:secret) | [IsMalicious](https://ismalicious.com/) |
| `NVD_API_KEY` (scanner) | Faster vuln-scan CVE lookups (50 req/30s vs ~5) | [NVD](https://nvd.nist.gov/developers/request-an-api-key) (free) |
Expand Down Expand Up @@ -554,7 +562,8 @@ Every data domain gets its own isolated route under `src/app/api/`:
- **🔄 Stateless API** — Backend routes are stateless and cache-friendly, enabling horizontal scaling
- **🛡️ SSRF protection** — `ssrf-guard.ts` validates all outbound URLs against private IP ranges before fetching
- **🔒 Proxy security** — CCTV proxies enforce strict host allowlists and content-type validation; HLS proxy includes CORS-aware origin headers
- **📦 Rate-limited endpoints** — AI analysis, IP sweep, and scanner endpoints all have per-IP rate limiting
- **📦 Rate-limited endpoints** — AI analysis, IP sweep, and scanner endpoints all have per-IP rate limiting (forwarding headers are trusted only with `TRUST_PROXY_HEADERS`)
- **🔑 Scanner access gate** — the RECON scanner proxy is closed to remote callers on production builds unless the operator sets `SCANNER_ACCESS_TOKEN` (or explicitly `SCANNER_ALLOW_ANONYMOUS=true`)
- **🔗 Entity linking** — Sanctions cross-checking and OFAC/SDN matching is built into WHOIS and IP intel routes

---
Expand Down
4 changes: 4 additions & 0 deletions nginx/nginx.conf
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,10 @@ http {
proxy_pass http://osiris:3000;

proxy_set_header Host $host;
# X-Real-IP is overwritten and X-Forwarded-For has $remote_addr
# APPENDED, so the rightmost XFF entry is the real client. OSIRIS
# reads it only when TRUST_PROXY_HEADERS=true (see .env.example);
# anything to its left is client-supplied and never trusted.
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
Expand Down
166 changes: 166 additions & 0 deletions src/app/api/scanner-access.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';

// OWASP A01: the scanner proxy must be closed to anonymous remote callers by
// default. Every test records what the route tries to fetch upstream.
let calls: string[] = [];
function stubFetch() {
calls = [];
vi.stubGlobal('fetch', vi.fn(async (input: RequestInfo | URL) => {
calls.push(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url);
return Response.json({ ok: true, scanned: true });
}));
}

const ENV_KEYS = ['SCANNER_URL', 'SCANNER_KEY', 'SCANNER_ACCESS_TOKEN', 'SCANNER_ALLOW_ANONYMOUS', 'TRUST_PROXY_HEADERS'] as const;

function setEnv(vars: Partial<Record<(typeof ENV_KEYS)[number] | 'NODE_ENV', string>>) {
for (const k of ENV_KEYS) vi.stubEnv(k, undefined as unknown as string);
vi.stubEnv('SCANNER_URL', 'http://scanner.test:7700');
vi.stubEnv('SCANNER_KEY', 'sidecar-secret');
for (const [k, v] of Object.entries(vars)) vi.stubEnv(k, v);
}

// The route reads SCANNER_URL/KEY at module load and ssrf-guard keeps its
// rate-limit map in module state, so import a fresh copy per test.
async function route() {
vi.resetModules();
return import('./scanner/route');
}

const PUBLIC_IP = '93.184.215.14'; // literal → no DNS in tests
function req(qs: string, headers: Record<string, string> = {}) {
return new Request(`http://osiris.example.com/api/scanner?${qs}`, {
headers: { host: 'osiris.example.com', ...headers },
});
}

beforeEach(() => stubFetch());
afterEach(() => {
vi.unstubAllGlobals();
vi.unstubAllEnvs();
});

describe('scanner: access gate', () => {
it('default config (no token, no opt-in, production) → 403 and no upstream fetch', async () => {
setEnv({ NODE_ENV: 'production' });
const { GET } = await route();
const res = await GET(req(`target=${PUBLIC_IP}&type=quick`));
expect(res.status).toBe(403);
expect(calls).toHaveLength(0);
});

it('token configured but missing → 401 (prompts the UI), no fetch', async () => {
setEnv({ NODE_ENV: 'production', SCANNER_ACCESS_TOKEN: 'correct-horse' });
const { GET } = await route();
const res = await GET(req(`target=${PUBLIC_IP}`));
expect(res.status).toBe(401);
expect((await res.json()).auth).toBe('token');
expect(calls).toHaveLength(0);
});

it('wrong token → 401, no fetch', async () => {
setEnv({ NODE_ENV: 'production', SCANNER_ACCESS_TOKEN: 'correct-horse' });
const { GET } = await route();
const res = await GET(req(`target=${PUBLIC_IP}`, { 'x-scanner-token': 'correct-hors' }));
expect(res.status).toBe(401);
expect(calls).toHaveLength(0);
});

it('correct token → proxied to the sidecar', async () => {
setEnv({ NODE_ENV: 'production', SCANNER_ACCESS_TOKEN: 'correct-horse' });
const { GET } = await route();
const res = await GET(req(`target=${PUBLIC_IP}&type=ssl`, { 'x-scanner-token': 'correct-horse' }));
expect(res.status).toBe(200);
expect(calls).toHaveLength(1);
expect(calls[0].startsWith('http://scanner.test:7700/scan/ssl?')).toBe(true);
});

it('SCANNER_ALLOW_ANONYMOUS=true → proxied without a token', async () => {
setEnv({ NODE_ENV: 'production', SCANNER_ALLOW_ANONYMOUS: 'true' });
const { GET } = await route();
const res = await GET(req(`target=${PUBLIC_IP}`));
expect(res.status).toBe(200);
expect(calls).toHaveLength(1);
});

it('next dev + loopback request → proxied with zero config', async () => {
setEnv({ NODE_ENV: 'development' });
const { GET } = await route();
const res = await GET(req(`target=${PUBLIC_IP}`, { host: 'localhost:3000', 'x-forwarded-for': '::1', 'sec-fetch-site': 'same-origin' }));
expect(res.status).toBe(200);
expect(calls).toHaveLength(1);
});

it.each([
['production build, localhost Host', 'production', { host: 'localhost:3000', 'x-forwarded-for': '::1' }],
['dev, public Host (LAN / DNS rebinding)', 'development', { host: 'osiris.example.com', 'x-forwarded-for': '::1' }],
['dev, non-loopback X-Forwarded-For (proxy)', 'development', { host: 'localhost:3000', 'x-forwarded-for': '203.0.113.9' }],
['dev, cross-site browser request', 'development', { host: 'localhost:3000', 'x-forwarded-for': '::1', 'sec-fetch-site': 'cross-site' }],
])('not treated as local: %s → 403, no fetch', async (_name, nodeEnv, headers) => {
setEnv({ NODE_ENV: nodeEnv });
const { GET } = await route();
const res = await GET(req(`target=${PUBLIC_IP}`, headers));
expect(res.status).toBe(403);
expect(calls).toHaveLength(0);
});

it('unconfigured scanner still answers 503', async () => {
setEnv({ NODE_ENV: 'production', SCANNER_ALLOW_ANONYMOUS: 'true' });
vi.stubEnv('SCANNER_KEY', '');
const { GET } = await route();
expect((await GET(req(`target=${PUBLIC_IP}`))).status).toBe(503);
expect(calls).toHaveLength(0);
});
});

describe('scanner: SSRF + scan-type allowlist unchanged for authorised callers', () => {
const auth = { 'x-scanner-token': 'correct-horse' };

it.each(['127.0.0.1', '169.254.169.254', '10.0.0.1', '::1', 'localhost', '2130706433'])('blocks internal target %s', async (target) => {
setEnv({ NODE_ENV: 'production', SCANNER_ACCESS_TOKEN: 'correct-horse' });
const { GET } = await route();
const res = await GET(req(`target=${encodeURIComponent(target)}`, auth));
expect(res.status).toBe(403);
expect((await res.json()).error).toBe('Target blocked');
expect(calls).toHaveLength(0);
});

it.each(['deep', 'ports', 'banner', 'traceroute', 'constructor'])('refuses restricted scan type %s', async (type) => {
setEnv({ NODE_ENV: 'production', SCANNER_ACCESS_TOKEN: 'correct-horse' });
const { GET } = await route();
const res = await GET(req(`target=${PUBLIC_IP}&type=${type}`, auth));
expect(res.status).toBe(403);
expect(calls).toHaveLength(0);
});

it('missing target → 400', async () => {
setEnv({ NODE_ENV: 'production', SCANNER_ACCESS_TOKEN: 'correct-horse' });
const { GET } = await route();
expect((await GET(req('type=quick', auth))).status).toBe(400);
});
});

describe('scanner: rate limit cannot be dodged with forged forwarding headers', () => {
it('rotating X-Forwarded-For does not reset the limit when proxy headers are untrusted', async () => {
setEnv({ NODE_ENV: 'production', SCANNER_ALLOW_ANONYMOUS: 'true' });
const { GET } = await route();
const statuses: number[] = [];
for (let i = 1; i <= 6; i++) {
const res = await GET(req(`target=${PUBLIC_IP}`, { 'x-forwarded-for': `198.51.100.${i}`, 'x-real-ip': `198.51.100.${i}` }));
statuses.push(res.status);
}
expect(statuses).toEqual([200, 200, 200, 200, 200, 429]);
});

it('with TRUST_PROXY_HEADERS=true, distinct proxy-reported clients get separate buckets', async () => {
setEnv({ NODE_ENV: 'production', SCANNER_ALLOW_ANONYMOUS: 'true', TRUST_PROXY_HEADERS: 'true' });
const { GET } = await route();
const statuses: number[] = [];
for (let i = 1; i <= 6; i++) {
// client-forged first entry stays constant; the proxy-appended last entry varies
const res = await GET(req(`target=${PUBLIC_IP}`, { 'x-forwarded-for': `1.1.1.1, 203.0.113.${i}` }));
statuses.push(res.status);
}
expect(statuses).toEqual([200, 200, 200, 200, 200, 200]);
});
});
15 changes: 13 additions & 2 deletions src/app/api/scanner/route.ts
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
import { NextResponse } from 'next/server';
import { validateHost, isRateLimited, getClientIp } from '@/lib/ssrf-guard';
import { checkScannerAccess } from '@/lib/scanner-access';

/**
* OSIRIS — Scanner Proxy (Hardened)
* Rate-limited, target-validated, scope-restricted
* Access-gated, rate-limited, target-validated, scope-restricted
*/

const SCANNER_URL = process.env.SCANNER_URL || '';
Expand Down Expand Up @@ -51,6 +52,15 @@ export async function GET(req: Request) {
}, { status: 429 });
}

// 2b. Access gate (OWASP A01): closed on public hosts unless the operator
// issues SCANNER_ACCESS_TOKEN or opts in with SCANNER_ALLOW_ANONYMOUS.
// Runs after the rate limit so token guesses are throttled too. See
// src/lib/scanner-access.ts for the threat model.
const access = checkScannerAccess(req);
if (!access.ok) {
return NextResponse.json(access.body, { status: access.status });
}

// 3. Validate params
const { searchParams } = new URL(req.url);
const target = searchParams.get('target')?.trim();
Expand All @@ -72,7 +82,8 @@ export async function GET(req: Request) {
}

// 5. Validate scan type (only safe scans allowed)
const scanConfig = ALLOWED_SCANS[scanType];
// Own keys only: `type=constructor` must not resolve via Object.prototype.
const scanConfig = Object.hasOwn(ALLOWED_SCANS, scanType) ? ALLOWED_SCANS[scanType] : undefined;
if (!scanConfig) {
return NextResponse.json({
error: 'Scan type not available',
Expand Down
38 changes: 37 additions & 1 deletion src/components/OsintPanel.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,40 @@ import {
} from 'lucide-react';
import { ipToNumber, numberToIp, calculateSubnetStart, classifyDevice, assessRisk, batchFetch, ShodanInternetDBResponse, SweepDevice } from '@/lib/osint-utils';

// ── Scanner access token (OWASP A01) ──
// On public deployments /api/scanner answers 401 unless the request carries
// the operator-issued SCANNER_ACCESS_TOKEN. Prompt once on a 401 and keep the
// token for this browser tab only (sessionStorage, not localStorage).
const SCANNER_TOKEN_STORAGE_KEY = 'osiris.scannerAccessToken';

function readScannerToken(): string {
try { return sessionStorage.getItem(SCANNER_TOKEN_STORAGE_KEY) || ''; } catch { return ''; }
}

function writeScannerToken(token: string | null): void {
try {
if (token) sessionStorage.setItem(SCANNER_TOKEN_STORAGE_KEY, token);
else sessionStorage.removeItem(SCANNER_TOKEN_STORAGE_KEY);
} catch { /* storage unavailable: token lives for this request only */ }
}

async function fetchScanner(url: string): Promise<Response> {
const send = (token: string) => fetch(url, token ? { headers: { 'X-Scanner-Token': token } } : undefined);
const stored = readScannerToken();
const res = await send(stored);
if (res.status !== 401) return res;
writeScannerToken(null);
const entered = window.prompt(
stored
? 'The saved scanner access token was rejected. Enter the SCANNER_ACCESS_TOKEN for this OSIRIS instance:'
: 'This OSIRIS instance requires a scanner access token. Enter the SCANNER_ACCESS_TOKEN issued by its operator:',
)?.trim();
if (!entered) return res;
const retry = await send(entered);
if (retry.status !== 401) writeScannerToken(entered);
return retry;
}

const TABS = [
{ id: 'scanner', label: 'PORT SCAN', icon: Radar, placeholder: 'IP or hostname', color: '#1A73E8' },
{ id: 'vuln', label: 'VULN SWEEP', icon: Bug, placeholder: 'IP or hostname', color: '#FF3D3D' },
Expand Down Expand Up @@ -223,7 +257,9 @@ function OsintPanelInner({ isMobile, onSweepVisualize, onScanGeolocate, onReconF
break;
}
}
const res = await fetch(url, activeTab === 'shodan' ? { cache: 'no-store' } : undefined);
const res = url.startsWith('/api/scanner')
? await fetchScanner(url)
: await fetch(url, activeTab === 'shodan' ? { cache: 'no-store' } : undefined);
if (activeTab === 'shodan' && res.status === 404) {
setResults({ ip: query, status: 'No Shodan InternetDB records found', ports: [], cpes: [], hostnames: [], tags: [], vulns: [] });
setLoading(false);
Expand Down
Loading
Loading