v3.5.3 — Integrations (GitHub · GitLab · Jira)

New harness module `integrations` (+ app commands) wiring NeuroSploit into the
SDLC. Config persists per-project to .neurosploit/integrations.json; secrets are
NEVER stored — only the env-var name is saved, values read from the environment.

GitHub:
- private-repo clone (token injected into the clone URL for whitebox/greybox/tui)
- `neurosploit pr <owner/repo> <n>`: clone the PR head (refs/pull/N/head),
  white-box review, optional `--comment` (PR summary) and `--jira` (cards)
- `neurosploit watch <owner/repo> --branch --interval`: re-review on each new commit
GitLab:
- private-repo clone (oauth2 token) for whitebox/greybox (gitlab.com or self-hosted)
Jira:
- `--jira` on any engagement opens one card per finding (REST /issue, basic auth)

Control:
- `/integrations` (REPL): show · enable/disable · setup jira|gitlab|github
- `neurosploit integrations [show|enable|disable] [github|gitlab|jira]` (CLI)

Docs: README "Integrations" section + new TUTORIAL-INTEGRATION.md (per-tool setup,
scopes, recipes, troubleshooting). Version bumped 3.5.2 → 3.5.3.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

TUTORIAL-INTEGRATION.md

@@ -0,0 +1,210 @@
+# NeuroSploit — Integrations Setup Guide (v3.5.3)
+
+Connect NeuroSploit to **GitHub**, **GitLab** and **Jira** so it can review private
+repositories and Pull Requests, watch branches for new code, and file a Jira
+**card per vulnerability**.
+
+> ⚠️ **Authorized testing only.** Use integrations against code/projects you own or
+> are explicitly permitted to test.
+
+---
+
+## Table of contents
+1. [How it works (config & secrets)](#1-how-it-works)
+2. [The `/integrations` command](#2-the-integrations-command)
+3. [GitHub](#3-github)
+4. [GitLab](#4-gitlab)
+5. [Jira](#5-jira)
+6. [Recipes](#6-recipes)
+7. [Troubleshooting](#7-troubleshooting)
+
+---
+
+## 1. How it works
+
+- Integration config is **per project**, stored at
+  `<cwd>/.neurosploit/integrations.json`.
+- **Secrets are never written to disk.** The config only stores the **name** of
+  the environment variable that holds each token (e.g. `GITHUB_TOKEN`). The real
+  value is read from your environment at use time. Keep tokens in your shell /
+  secret manager, not in the repo.
+- Enable/disable per integration; each is independent.
+
+Default env-var names (configurable):
+
+| Integration | Token env var(s) |
+|-------------|------------------|
+| GitHub | `GITHUB_TOKEN` |
+| GitLab | `GITLAB_TOKEN` |
+| Jira | `JIRA_EMAIL` + `JIRA_API_TOKEN` |
+
+---
+
+## 2. The `/integrations` command
+
+In the **REPL** (`neurosploit` with no args):
+
+```
+/integrations                      # show status of all three
+/integrations enable github        # toggle on   (also: gitlab | jira)
+/integrations disable jira         # toggle off
+/integrations setup jira           # interactive: base URL, project key, issue type
+/integrations setup gitlab         # set the GitLab base (gitlab.com or self-hosted)
+/integrations setup github         # set the API base (change only for GitHub Enterprise)
+```
+
+From the **CLI**:
+
+```bash
+neurosploit integrations                       # show status
+neurosploit integrations enable github         # enable / disable <github|gitlab|jira>
+```
+
+`show` prints whether each is on and whether the token env var is currently set
+(`✓ token` / `⚠ token env not set`).
+
+---
+
+## 3. GitHub
+
+**a. Create a token.** GitHub → *Settings → Developer settings → Personal access
+tokens*. A classic PAT with the **`repo`** scope (read access to the private repos
+you'll test) is enough. Fine-grained tokens also work (grant *Contents: Read* and,
+for PR comments, *Pull requests: Read & write*).
+
+**b. Export it and enable:**
+```bash
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+neurosploit integrations enable github
+```
+
+**c. What you can now do:**
+
+- **Clone & review a private repo** (token is injected into the clone URL,
+  never printed):
+  ```bash
+  neurosploit whitebox https://github.com/myorg/private-app \
+    --subscription --model anthropic:claude-opus-4-8 -v
+  ```
+- **Review a Pull Request's code** — clones the PR head (`refs/pull/N/head`):
+  ```bash
+  neurosploit pr myorg/private-app 128 \
+    --subscription --model anthropic:claude-opus-4-8 --comment
+  ```
+  - `--comment` posts a Markdown findings summary back on the PR.
+  - `--jira` also opens a card per finding (needs Jira configured).
+- **Watch a branch** and re-review on every new commit:
+  ```bash
+  neurosploit watch myorg/private-app --branch main --interval 300 \
+    --subscription --model anthropic:claude-opus-4-8
+  ```
+  It polls the branch tip via the GitHub API and runs a white-box review whenever
+  the SHA changes (Ctrl-C to stop).
+
+**GitHub Enterprise:** `/integrations setup github` and set the API base to your
+GHE URL (e.g. `https://ghe.mycorp.com/api/v3`).
+
+---
+
+## 4. GitLab
+
+**a. Create a token.** GitLab → *Preferences → Access Tokens* (or a project/group
+token) with the **`read_repository`** scope (add `api` if you want more later).
+
+**b. Export it and enable:**
+```bash
+export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
+neurosploit integrations enable gitlab
+# self-hosted? set the base:
+#   /integrations setup gitlab   →  https://gitlab.mycorp.com
+```
+
+**c. Review a private GitLab repo** (token-injected clone, works in whitebox &
+greybox):
+```bash
+neurosploit whitebox https://gitlab.com/myorg/private-svc \
+  --subscription --model anthropic:claude-opus-4-8 -v
+```
+
+> To review a specific Merge Request, check out its source branch and point
+> `whitebox` at that clone, or pass the MR source branch URL.
+
+---
+
+## 5. Jira
+
+**a. Create an API token.** https://id.atlassian.com/manage-profile/security/api-tokens
+→ *Create API token*. Note the email of the Atlassian account that owns it.
+
+**b. Export credentials:**
+```bash
+export JIRA_EMAIL=you@yourorg.com
+export JIRA_API_TOKEN=xxxxxxxxxxxxxxxxxxxx
+```
+
+**c. Configure base URL + project (once):**
+```
+# in the REPL:
+/integrations setup jira
+  Jira base URL (https://your-org.atlassian.net):  https://yourorg.atlassian.net
+  Jira project key (e.g. SEC):                     SEC
+  Issue type [Bug]:                                Bug
+```
+This enables Jira and saves the base URL / project key / issue type to
+`.neurosploit/integrations.json` (no secrets).
+
+**d. Open cards.** Add `--jira` to any engagement (or `pr` / `watch`). One card is
+created per **validated** finding, with severity, CVSS, CWE, location, PoC,
+evidence and remediation:
+```bash
+neurosploit whitebox https://github.com/myorg/app --jira \
+  --subscription --model anthropic:claude-opus-4-8 -v
+```
+The created issue keys are printed (e.g. `🪪 Jira cards opened: SEC-481, SEC-482`).
+
+> Uses the Jira REST API (`POST /rest/api/2/issue`) with Basic auth
+> (`JIRA_EMAIL` : `JIRA_API_TOKEN`). The `issuetype` must exist in your project
+> (use `Vulnerability` if your project defines it).
+
+---
+
+## 6. Recipes
+
+**PR gate in CI** (block a PR if Critical/High findings appear):
+```bash
+export GITHUB_TOKEN=...   # CI secret
+neurosploit integrations enable github
+neurosploit pr "$REPO" "$PR_NUMBER" --model anthropic:claude-opus-4-8 --comment --jira
+```
+
+**Nightly drift review** of a private app, filing Jira cards:
+```bash
+neurosploit integrations enable github
+neurosploit integrations enable jira
+neurosploit watch myorg/app --branch main --interval 3600 --jira \
+  --model anthropic:claude-opus-4-8
+```
+
+**Local private-repo audit** (no PR), cards to Jira:
+```bash
+neurosploit whitebox https://github.com/myorg/app --jira \
+  --subscription --model anthropic:claude-opus-4-8 -v
+```
+
+---
+
+## 7. Troubleshooting
+
+- **`⚠ token env not set`** — the integration is enabled but the env var isn't
+  exported in this shell. Export it (`export GITHUB_TOKEN=...`) and re-run.
+- **`git clone failed` on a private repo** — confirm the token scope (`repo` /
+  `read_repository`) and that the integration is enabled (`neurosploit
+  integrations`). The token is only injected when the matching integration is on.
+- **`jira create failed: 400`** — the `issuetype` name doesn't exist in the
+  project, or a required field is enforced. Try `Bug`, or set your project's type
+  via `/integrations setup jira`.
+- **`jira ... not set`** — export `JIRA_EMAIL` and `JIRA_API_TOKEN`.
+- **GitHub comment fails (403/404)** — the token needs *Pull requests: write*
+  (fine-grained) or `repo` (classic), and you must have access to the repo.
+- **Tokens in CI** — pass them as masked secrets; NeuroSploit never logs or
+  stores token values.