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
102 changes: 102 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
# Attack Surface Studio

A Knowledge Graph platform for security reconnaissance and assessment. It orchestrates
external security tools (Nmap, ffuf, Nuclei, …), normalizes their heterogeneous output into
a single graph model, and turns an engagement's accumulated evidence — scans, manual
findings, screenshots, notes, reports — into one navigable, queryable body of knowledge.

The Knowledge Graph is the product. Security tools are data sources only: every adapter
ultimately produces exactly three things — **Nodes**, **Edges**, and **Metadata** — and
those are what the rest of the platform (UI, reports, AI assistant) reads from. See
[`.claude/Claude.md`](.claude/Claude.md) for the full project philosophy and architecture
docs (`ARCHITECTURE.md`, `DATA_MODEL.md`, `INTEGRATION_SYSTEM.md`, `SECURITY_MODEL.md`,
`Plan.md`).

## Stack

| Layer | Choice |
|---|---|
| Frontend | Next.js 16 (App Router), React 19, TypeScript strict, Tailwind v4, React Flow, Zustand, TanStack Query |
| Backend | NestJS, TypeScript, Drizzle ORM, BullMQ (Redis-backed job queue) |
| Database | PostgreSQL 16 |
| Tool execution | `child_process` (local) / `dockerode` (Docker) behind a Tool Adapter registry (`nmap`, `ffuf`, `nuclei`, …) |
| Auth | JWT (short-lived access + rotating refresh), Argon2id password hashing |
| Testing | Vitest + Supertest (integration), Playwright (E2E) |

## Project layout

```
Attack Surface Studio/
├── client/ Next.js frontend (marketing Hero + Graph Engine + authenticated Workspace)
├── server/ NestJS backend (auth, orchestrator, adapters, knowledge graph, reports)
├── db/ Postgres bootstrap scripts (docker-entrypoint-initdb.d)
├── docker-compose.yml Local Postgres + Redis
└── .claude/ Architecture and planning documentation (source of truth)
```

## Prerequisites

- Node.js 20+
- [pnpm](https://pnpm.io/) 9
- Docker (for local Postgres + Redis via `docker-compose`)

## Getting started

1. **Start the datastores**

```bash
cp .env.example .env # fill in real values before running in anything but local dev
docker-compose up -d
```

2. **Backend** (`server/`)

```bash
cd server
pnpm install
cp .env.example .env # DATABASE_URL, JWT secrets, REDIS_URL, etc. — see file comments
pnpm migrate
pnpm start:dev # API on http://localhost:3001
pnpm start:worker:dev # separate process: executes queued tool runs
```

3. **Frontend** (`client/`)

```bash
cd client
pnpm install
cp .env.example .env # NEXT_PUBLIC_API_URL=http://localhost:3001
pnpm dev # App on http://localhost:3000
```

4. Open [http://localhost:3000](http://localhost:3000). The landing page's "Request access" /
"Sign in" buttons lead to `/register` and `/login`; once authenticated you land on `/app`.

## Testing

```bash
# Frontend
cd client && pnpm test # Vitest + Testing Library
cd client && pnpm e2e # Playwright

# Backend
cd server && pnpm test # Vitest + Supertest
cd server && pnpm test:coverage
```

Both projects enforce an 80% coverage floor. Adapter tests run against recorded real tool
output fixtures rather than live scans.

## Documentation

Everything beyond this quick-start — vision, data model, security posture, the phased
roadmap, and the development log — lives in [`.claude/`](.claude):

- [`Claude.md`](.claude/Claude.md) — vision, philosophy, stack, standards (start here)
- [`ARCHITECTURE.md`](.claude/ARCHITECTURE.md) — system decomposition
- [`DATA_MODEL.md`](.claude/DATA_MODEL.md) — PostgreSQL schema for the graph
- [`INTEGRATION_SYSTEM.md`](.claude/INTEGRATION_SYSTEM.md) — the Tool Adapter contract
- [`SECURITY_MODEL.md`](.claude/SECURITY_MODEL.md) — cross-cutting security posture
- [`Plan.md`](.claude/Plan.md) — the phased roadmap
- [`Progress.md`](.claude/Progress.md) — development log
- [`Routes.md`](.claude/Routes.md) — routing registry
9 changes: 9 additions & 0 deletions client/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
<!-- BEGIN:nextjs-agent-rules -->

# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

<!-- END:nextjs-agent-rules -->
1 change: 1 addition & 0 deletions client/CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
@AGENTS.md
21 changes: 15 additions & 6 deletions client/src/app/login/page.tsx
Original file line number Diff line number Diff line change
@@ -1,20 +1,29 @@
import Link from "next/link";
import type { Metadata } from "next";
import { Radar } from "lucide-react";
import { LoginForm } from "@/features/auth/components/LoginForm";
import { BackgroundLayer } from "@/components/effects/BackgroundLayer";

export const metadata: Metadata = {
title: "Sign in — Attack Surface Studio",
};

export default function LoginPage() {
return (
<main className="flex min-h-screen flex-1 items-center justify-center bg-[var(--color-background)] px-6">
<div className="flex w-full max-w-sm flex-col gap-8">
<div className="flex flex-col gap-2 text-center">
<h1 className="text-2xl font-semibold text-[var(--color-foreground)]">Sign in</h1>
<p className="text-sm text-[var(--color-foreground-muted)]">Access your Attack Surface Studio workspace.</p>
<main className="relative flex min-h-screen flex-1 items-center justify-center bg-[var(--color-background)] px-6">
<BackgroundLayer />
<div className="relative z-10 flex w-full max-w-sm flex-col gap-8">
<Link href="/" className="flex items-center justify-center gap-2 text-[var(--color-foreground)]">
<Radar size={20} strokeWidth={2} className="text-[var(--color-accent-strong)]" />
<span className="text-sm font-semibold tracking-tight">Attack Surface Studio</span>
</Link>
<div className="rounded-[var(--radius-xl)] border border-[var(--color-border)] bg-[var(--color-surface)] p-8 shadow-[0_0_40px_-12px_var(--glow-primary)]">
<div className="flex flex-col gap-2 pb-6 text-center">
<h1 className="text-2xl font-semibold text-[var(--color-foreground)]">Sign in</h1>
<p className="text-sm text-[var(--color-foreground-muted)]">Access your Attack Surface Studio workspace.</p>
</div>
<LoginForm />
</div>
<LoginForm />
<p className="text-center text-sm text-[var(--color-foreground-subtle)]">
Don&apos;t have an account?{" "}
<Link href="/register" className="text-[var(--color-accent)] hover:underline">
Expand Down
9 changes: 7 additions & 2 deletions client/src/app/page.tsx
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
import { cookies } from 'next/headers'
import { HeroSection } from '@/features/hero/HeroSection'
import { REFRESH_TOKEN_COOKIE } from '@/lib/auth-cookies'

export default function Home() {
return <HeroSection />
export default async function Home() {
const cookieStore = await cookies()
const hasSession = cookieStore.has(REFRESH_TOKEN_COOKIE)

return <HeroSection hasSession={hasSession} />
}
21 changes: 15 additions & 6 deletions client/src/app/register/page.tsx
Original file line number Diff line number Diff line change
@@ -1,20 +1,29 @@
import Link from "next/link";
import type { Metadata } from "next";
import { Radar } from "lucide-react";
import { RegisterForm } from "@/features/auth/components/RegisterForm";
import { BackgroundLayer } from "@/components/effects/BackgroundLayer";

export const metadata: Metadata = {
title: "Create account — Attack Surface Studio",
};

export default function RegisterPage() {
return (
<main className="flex min-h-screen flex-1 items-center justify-center bg-[var(--color-background)] px-6">
<div className="flex w-full max-w-sm flex-col gap-8">
<div className="flex flex-col gap-2 text-center">
<h1 className="text-2xl font-semibold text-[var(--color-foreground)]">Create your account</h1>
<p className="text-sm text-[var(--color-foreground-muted)]">Start mapping your attack surface.</p>
<main className="relative flex min-h-screen flex-1 items-center justify-center bg-[var(--color-background)] px-6">
<BackgroundLayer />
<div className="relative z-10 flex w-full max-w-sm flex-col gap-8">
<Link href="/" className="flex items-center justify-center gap-2 text-[var(--color-foreground)]">
<Radar size={20} strokeWidth={2} className="text-[var(--color-accent-strong)]" />
<span className="text-sm font-semibold tracking-tight">Attack Surface Studio</span>
</Link>
<div className="rounded-[var(--radius-xl)] border border-[var(--color-border)] bg-[var(--color-surface)] p-8 shadow-[0_0_40px_-12px_var(--glow-primary)]">
<div className="flex flex-col gap-2 pb-6 text-center">
<h1 className="text-2xl font-semibold text-[var(--color-foreground)]">Create your account</h1>
<p className="text-sm text-[var(--color-foreground-muted)]">Start mapping your attack surface.</p>
</div>
<RegisterForm />
</div>
<RegisterForm />
<p className="text-center text-sm text-[var(--color-foreground-subtle)]">
Already have an account?{" "}
<Link href="/login" className="text-[var(--color-accent)] hover:underline">
Expand Down
2 changes: 1 addition & 1 deletion client/src/components/ui/button.tsx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { cva, type VariantProps } from 'class-variance-authority'
import { cn } from '@/lib/utils'

const buttonVariants = cva(
export const buttonVariants = cva(
'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-full text-sm font-medium transition-all duration-200 ease-out focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-accent)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--color-background)] disabled:pointer-events-none disabled:opacity-50',
{
variants: {
Expand Down
8 changes: 5 additions & 3 deletions client/src/features/evidence/api/use-evidence.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,15 @@ const EVIDENCE = {
describe("useEvidence", () => {
afterEach(() => vi.clearAllMocks());

it("fetches and Zod-parses the project's evidence list", async () => {
it("fetches and Zod-parses the project's evidence list, requesting the server's max page size (BUG #12 sibling)", async () => {
// EvidenceGrid has no pager UI -- without an explicit pageSize, a project with more than
// DEFAULT_PAGE_SIZE=25 evidence files would silently lose access to the rest, with no indication.
vi.mocked(apiRequestPaginated).mockResolvedValue({ items: [EVIDENCE] });

const { result } = renderHook(() => useEvidence(PROJECT_ID), { wrapper: queryClientWrapper() });

await waitFor(() => expect(result.current.data).toHaveLength(1));
expect(apiRequestPaginated).toHaveBeenCalledWith(`/projects/${PROJECT_ID}/evidence`);
expect(apiRequestPaginated).toHaveBeenCalledWith(`/projects/${PROJECT_ID}/evidence?pageSize=100`);
});

it("scopes the query by nodeId when provided", async () => {
Expand All @@ -38,7 +40,7 @@ describe("useEvidence", () => {
renderHook(() => useEvidence(PROJECT_ID, "node-1"), { wrapper: queryClientWrapper() });

await waitFor(() =>
expect(apiRequestPaginated).toHaveBeenCalledWith(`/projects/${PROJECT_ID}/evidence?nodeId=node-1`),
expect(apiRequestPaginated).toHaveBeenCalledWith(`/projects/${PROJECT_ID}/evidence?nodeId=node-1&pageSize=100`),
);
});
});
7 changes: 5 additions & 2 deletions client/src/features/evidence/api/use-evidence.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,12 @@ export function useEvidence(projectId: string, nodeId?: string) {
return useQuery({
queryKey: ["projects", projectId, "evidence", { nodeId: nodeId ?? null }] as const,
queryFn: async () => {
// Same fix as use-projects.ts (BUG #12): request the server's hard page-size cap since
// EvidenceGrid has no pager UI, so anything past DEFAULT_PAGE_SIZE=25 would otherwise
// silently vanish from view.
const path = nodeId
? `/projects/${projectId}/evidence?nodeId=${encodeURIComponent(nodeId)}`
: `/projects/${projectId}/evidence`;
? `/projects/${projectId}/evidence?nodeId=${encodeURIComponent(nodeId)}&pageSize=100`
: `/projects/${projectId}/evidence?pageSize=100`;
const { items } = await apiRequestPaginated<unknown[]>(path);
return evidenceFileListSchema.parse(items);
},
Expand Down
17 changes: 12 additions & 5 deletions client/src/features/hero/HeroSection.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import { CTAGroup } from './components/CTAGroup'
import { GraphStage } from './components/GraphStage'
import { InfoSection } from './components/InfoSection'
import { Footer } from './components/Footer'
import { BackgroundLayer } from './background/BackgroundLayer'
import { BackgroundLayer } from '@/components/effects/BackgroundLayer'

const GraphPreview = dynamic(() => import('./components/GraphPreview'), {
ssr: false,
Expand Down Expand Up @@ -56,18 +56,25 @@ const HOW_IT_WORKS_ITEMS = [
},
]

export function HeroSection() {
interface HeroSectionProps {
hasSession: boolean
}

export function HeroSection({ hasSession }: HeroSectionProps) {
const graphStageRef = useRef<HTMLDivElement>(null)

return (
<div className="relative flex flex-1 flex-col">
<BackgroundLayer focusRef={graphStageRef} />
<Navbar />
<Navbar isAuthenticated={hasSession} />
<main className="relative z-10 mx-auto flex w-full max-w-3xl flex-col items-center gap-10 px-6 py-16 text-center sm:px-10 lg:py-24">
<HeroContent />
<CTAGroup />
<CTAGroup isAuthenticated={hasSession} />
</main>
<div className="relative z-10 mx-auto w-full max-w-[1600px] px-6 py-[var(--space-section)] sm:px-10">
<div
id="graph-preview"
className="relative z-10 mx-auto w-full max-w-[1600px] px-6 py-[var(--space-section)] sm:px-10"
>
<GraphStage containerRef={graphStageRef}>
<GraphPreview />
</GraphStage>
Expand Down
28 changes: 28 additions & 0 deletions client/src/features/hero/components/CTAGroup.test.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
import { afterEach, describe, expect, it } from "vitest";
import { cleanup, render, screen } from "@testing-library/react";
import { CTAGroup } from "./CTAGroup";

describe("CTAGroup", () => {
afterEach(cleanup);

it("links the primary CTA to registration when the visitor has no session", () => {
render(<CTAGroup isAuthenticated={false} />);

expect(screen.getByRole("link", { name: /Request access/ })).toHaveAttribute("href", "/register");
});

it("links the primary CTA to the app once the visitor has a session", () => {
render(<CTAGroup isAuthenticated={true} />);

expect(screen.getByRole("link", { name: /Go to app/ })).toHaveAttribute("href", "/app");
});

it("scrolls to the graph preview instead of navigating away", () => {
render(<CTAGroup isAuthenticated={false} />);

expect(screen.getByRole("link", { name: "Explore the graph engine" })).toHaveAttribute(
"href",
"#graph-preview",
);
});
});
22 changes: 15 additions & 7 deletions client/src/features/hero/components/CTAGroup.tsx
Original file line number Diff line number Diff line change
@@ -1,16 +1,24 @@
import Link from 'next/link'
import { ArrowRight } from 'lucide-react'
import { Button } from '@/components/ui/button'
import { buttonVariants } from '@/components/ui/button'

interface CTAGroupProps {
isAuthenticated: boolean
}

export function CTAGroup({ isAuthenticated }: CTAGroupProps) {
const ctaHref = isAuthenticated ? '/app' : '/register'
const ctaLabel = isAuthenticated ? 'Go to app' : 'Request access'

export function CTAGroup() {
return (
<div className="flex flex-col gap-4 sm:flex-row sm:items-center">
<Button size="lg">
Request access
<Link href={ctaHref} className={buttonVariants({ size: 'lg' })}>
{ctaLabel}
<ArrowRight size={16} />
</Button>
<Button variant="ghost" size="lg">
</Link>
<Link href="#graph-preview" className={buttonVariants({ variant: 'ghost', size: 'lg' })}>
Explore the graph engine
</Button>
</Link>
</div>
)
}
27 changes: 27 additions & 0 deletions client/src/features/hero/components/Navbar.test.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
import { afterEach, describe, expect, it } from "vitest";
import { cleanup, render, screen } from "@testing-library/react";
import { Navbar } from "./Navbar";

describe("Navbar", () => {
afterEach(cleanup);

it("links the CTA to registration when the visitor has no session", () => {
render(<Navbar isAuthenticated={false} />);

const cta = screen.getByRole("link", { name: "Request access" });
expect(cta).toHaveAttribute("href", "/register");
});

it("links the CTA to the app once the visitor has a session", () => {
render(<Navbar isAuthenticated={true} />);

const cta = screen.getByRole("link", { name: "Go to app" });
expect(cta).toHaveAttribute("href", "/app");
});

it("links the brand mark back to the homepage", () => {
render(<Navbar isAuthenticated={false} />);

expect(screen.getByRole("link", { name: /Attack Surface Studio/ })).toHaveAttribute("href", "/");
});
});
Loading
Loading