feat: brand the npm page, CLI output, and reports (#432)

* docs: rebuild the npm package README on the main README's identity * docs: point the README banner fallback at an asset that exists * docs: declare the npm package author, homepage, and issue tracker * docs(cli): retire "Framework" and settle on the canonical product line * docs: describe the banner image in alt text instead of repeating the lockup * feat(cli): print a plain-text banner when stdout is not a terminal * feat(report): attribute the markdown report from a shared brand constant * feat(cli): frame the plain-text banner with rules and split the version line * docs: drop the URL from the npm author field
2026-08-28 22:10:45 +02:00 · 2026-08-27 18:53:56 +05:30
parent ed5659e2e2
commit dc2a4fe4e8
10 changed files with 105 additions and 22 deletions
@@ -6,7 +6,7 @@
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="./assets/github-banner-dark.png">
 <source media="(prefers-color-scheme: light)" srcset="./assets/github-banner-light.png">
-<img src="./assets/github-banner.png" alt="Shannon - AI Pentester by Keygraph" width="100%">
+<img src="./assets/github-banner-light.png" alt="Shannon, AI Pentester for Web Apps and APIs, by Keygraph" width="100%">
 </picture>

 <a href="https://trendshift.io/repositories/15604" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15604" alt="KeygraphHQ%2Fshannon | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
@@ -1,22 +1,60 @@
 <div align="center">

-<img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/github-banner.png" alt="Shannon — AI Pentester for Web Applications and APIs" width="100%">
+<img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/github-banner-light.png" alt="Shannon, AI Pentester for Web Apps and APIs, by Keygraph" width="100%">

-# Shannon — AI Pentester by Keygraph
+### Shannon is an autonomous, AI pentester for web applications and APIs.

-Shannon is an autonomous, white-box AI pentester for web applications and APIs. <br />
-It analyzes your source code, identifies attack vectors, and executes real exploits to prove vulnerabilities before they reach production.
+It analyzes your source code, identifies attack paths, and executes real exploits to prove vulnerabilities before they reach production.
+
+**This package is Shannon Open Source: the full agent, run locally from your command line.**

 ---

-<a href="https://github.com/KeygraphHQ/shannon/discussions/categories/announcements"><img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/announcements.png" height="40" alt="Announcements"></a>
-<a href="https://discord.gg/9ZqQPuhJB7"><img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/discord.png" height="40" alt="Join Discord"></a>
-<a href="https://keygraph.io/"><img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/Keygraph_Button.png" height="40" alt="Visit Keygraph.io"></a>
-<a href="https://www.linkedin.com/company/keygraph/"><img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/linkedin.png" height="40" alt="Follow Us on Linkedin"></a>
+<a href="https://discord.gg/9ZqQPuhJB7"><img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/discord_button_light.png" height="40" alt="Join Discord"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://keygraph.io/"><img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/keygraph_button_light.png" height="40" alt="Visit Keygraph.io"></a>

 ---

-**Full README and usage guide**  
-[https://github.com/KeygraphHQ/shannon#readme](https://github.com/KeygraphHQ/shannon#readme)
-
 </div>
+
+## Quick Start
+
+### Prerequisites
+
+- **Docker**: required for the worker container.
+- **Node.js 18+**: required for the recommended `npx` workflow.
+- **AI provider credentials**: Shannon runs on Anthropic, OpenAI, xAI, AWS Bedrock, any other provider in the harness catalogue, and any endpoint that speaks the Anthropic Messages API or the OpenAI Chat Completions or Responses API through a custom base URL. You bring your own key, and Keygraph never proxies your model traffic. Shannon is provider-agnostic.
+- **Cyber safeguards cleared with your provider**: Anthropic and OpenAI apply real-time safeguards to cyber-security workloads, which can interrupt a scan mid-run. Complete their guidance for legitimate security testers before your first run.
+
+### Run Shannon
+
+> **Warning:** Shannon actively executes exploits. Run it only against applications and environments you own or have explicit written authorization to test. Do not run Shannon against production systems.
+
+```bash
+# Configure credentials with the interactive wizard.
+npx @keygraph/shannon setup
+
+# Run a pentest against a source-available target.
+npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo
+```
+
+Shannon pulls the worker image from Docker Hub, starts the required local infrastructure, mounts the target repository read-only inside an ephemeral worker container, and writes results to a local workspace.
+
+## Editions
+
+Shannon ships in two ways. **Shannon Open Source** is this package: the standalone pentester you run yourself, on demand, and complete in that lane. The **Keygraph platform** is the commercial product that runs an enhanced build of Shannon continuously and closes the full AppSec lifecycle around it - code analysis, finding management, automated remediation, verification, and enterprise deployment.
+
+## Documentation
+
+**Full README, guides, and usage documentation:** [github.com/KeygraphHQ/shannon](https://github.com/KeygraphHQ/shannon#readme)
+
+## License
+
+Shannon Open Source is licensed under the [GNU Affero General Public License v3.0](https://github.com/KeygraphHQ/shannon/blob/main/LICENSE).
+
+Commercial and enterprise licensing is available for organizations that need different license terms, commercial support, private redistribution, managed-service use, or broader deployment options, including the Keygraph platform.
+
+For commercial licensing, contact [shannon@keygraph.io](mailto:shannon@keygraph.io).
+
+<p align="center">
+  <b>Built by <a href="https://keygraph.io">Keygraph</a></b>
+</p>
@@ -1,7 +1,7 @@
 {
  "name": "@keygraph/shannon",
  "version": "0.0.0",
-  "description": "Shannon - Autonomous white-box AI pentester for web applications and APIs by Keygraph",
+  "description": "Shannon is an autonomous white-box AI pentester for web applications and APIs, by Keygraph.",
  "type": "module",
  "main": "dist/index.mjs",
  "bin": {
@@ -35,8 +35,12 @@
    "appsec",
    "keygraph"
  ],
-  "author": "",
+  "author": "Keygraph, Inc.",
  "license": "AGPL-3.0-only",
+  "bugs": {
+    "url": "https://github.com/KeygraphHQ/shannon/issues"
+  },
+  "homepage": "https://github.com/KeygraphHQ/shannon#readme",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/KeygraphHQ/shannon.git",
@@ -26,7 +26,7 @@ import {
 } from '../paths.js';
 import { indentFailureSegments } from '../scan/failure.js';
 import { resolveWorkflowId } from '../session.js';
-import { displaySplash } from '../splash.js';
+import { displayPlainBanner, displaySplash } from '../splash.js';
 import { getTerminalOutcome } from '../temporal-client.js';
 import { stdoutIsTerminal } from '../tty.js';
 import { tailUntilComplete } from './logs.js';
@@ -81,10 +81,12 @@ export async function start(args: StartArgs): Promise<void> {
  const repo = resolveRepo(args.repo);
  const config = args.config ? resolveConfig(args.config) : undefined;

-  // Inputs are valid — show the splash before the Docker/Temporal setup work.
-  // Skip it off a real terminal (e.g. CI) so piped/logged output stays clean.
+  // Inputs are valid — identify the run before the Docker/Temporal setup work.
+  const bannerVersion = isLocal() ? undefined : args.version;
  if (stdoutIsTerminal()) {
-    displaySplash(isLocal() ? undefined : args.version);
+    displaySplash(bannerVersion);
+  } else {
+    displayPlainBanner(bannerVersion);
  }

  // 4. Ensure workspaces dir is writable by container user (UID 1001)
@@ -1,5 +1,5 @@
 /**
- * Shannon CLI — AI Penetration Testing Framework
+ * Shannon CLI — AI Pentester for Web Apps and APIs
 *
 * Unified CLI supporting two modes:
 *   Local mode: Run from cloned repo — builds locally, mounts prompts, uses ./workspaces/
@@ -79,7 +79,7 @@ function showHelp(withSplash: boolean): void {
  const mode = getMode();
  const prefix = commandPrefix();

-  const header = withSplash ? '' : '\nShannon - AI Penetration Testing Framework\n';
+  const header = withSplash ? '' : '\nShannon — AI Pentester by Keygraph\n';

  console.log(`${header}
 Usage:
@@ -75,3 +75,20 @@ export function displaySplash(version?: string): void {

  console.log(lines.join('\n'));
 }
+
+/** Matches the divider width the CI wrappers and the scan renderer already use. */
+const RULE_WIDTH = 60;
+
+/**
+ * Plain-text banner for non-terminal output (CI logs, pipes, redirects).
+ * Drops the wordmark but keeps the authorized-use notice, which a reader of
+ * someone else's pipeline log still needs to see.
+ */
+export function displayPlainBanner(version?: string): void {
+  const rule = '─'.repeat(RULE_WIDTH);
+  console.log(rule);
+  console.log(version ? ` Shannon v${version}` : ' Shannon');
+  console.log(' AI Pentester for Web Apps and APIs, by Keygraph');
+  console.log(' Authorized security testing only.');
+  console.log(rule);
+}
@@ -0,0 +1,18 @@
+// Copyright (C) 2025 Keygraph, Inc.
+
+/**
+ * Centralized brand strings for report deliverables.
+ *
+ * Kept in two parts because the two renderers join them differently: the Typst
+ * template splits its `brand` input on a pipe to set the cover's two lines
+ * (`report.typ:212`), while a human-read line takes an em dash.
+ */
+
+export const PRODUCT_NAME = 'Shannon';
+export const PRODUCT_DESCRIPTOR = 'AI Pentester by Keygraph';
+
+/** Cover wordmark for the Typst template, which parses the pipe. */
+export const TYPST_BRAND = `${PRODUCT_NAME} | ${PRODUCT_DESCRIPTOR}`;
+
+/** Attribution line for prose surfaces. */
+export const BRAND_LOCKUP = `${PRODUCT_NAME} — ${PRODUCT_DESCRIPTOR}`;
@@ -22,13 +22,14 @@ import { copyFile, cp, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
+import { TYPST_BRAND } from '../branding.js';
 import { adaptReportToTypst } from './report-json-adapter.js';
 import type { ReportData } from './report-renderer.js';

 const execFileAsync = promisify(execFile);

 const DEFAULT_TESTER = 'Shannon';
-const DEFAULT_BRAND = 'Shannon | AI Pentester by Keygraph';
+const DEFAULT_BRAND = TYPST_BRAND;

 const DATA_FILENAME = 'data.json';
 const TEMPLATE_FILENAME = 'report.typ';
@@ -12,6 +12,7 @@
 * report agent previously wrote by hand. No LLM in the loop.
 */

+import { BRAND_LOCKUP } from '../branding.js';
 import type { AddFindingInput, AdditionalSection, StepItem, StructuredStep } from '../collectors/finding-collector.js';
 import type { VulnClass } from '../types/config.js';

@@ -212,6 +213,8 @@ export function renderReport(data: ReportData): string {
  // 1. Executive Summary
  sections.push('# Security Assessment Report');
  sections.push('');
+  sections.push(`*${BRAND_LOCKUP}*`);
+  sections.push('');
  sections.push('## Executive Summary');
  sections.push(`- Target: ${report_meta.target}`);
  sections.push(`- Assessment Date: ${report_meta.assessment_date}`);
@@ -15,7 +15,7 @@
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="./assets/github-banner-dark.png">
 <source media="(prefers-color-scheme: light)" srcset="./assets/github-banner-light.png">
-<img src="./assets/github-banner.png" alt="Shannon - AI Pentester by Keygraph" width="100%">
+<img src="./assets/github-banner-light.png" alt="Shannon, AI Pentester for Web Apps and APIs, by Keygraph" width="100%">
 </picture>

 <a href="https://trendshift.io/repositories/15604" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15604" alt="KeygraphHQ%2Fshannon | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>