NeuroSploit/TUTORIAL-INTEGRATION.md

NeuroSploit — Integrations Setup Guide

Connect NeuroSploit to GitHub, GitLab and Jira so it can review private repositories and Pull Requests, gate merges on severe findings, watch branches for new code, run from a @neurosploit comment, 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)
2. The /integrations command
3. GitHub
4. GitLab
5. Jira
6. Recipes
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:

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:

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):

  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):

  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:

  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).
• Gate a Pull Request — block the merge when a confirmed finding is severe:

  neurosploit pr myorg/private-app 128 \
    --model anthropic:claude-opus-4-8 --comment --fail-on critical
  

  --fail-on <critical|high|medium|low> does three things when a confirmed finding is at/above the threshold: the CLI exits non-zero (so a CI check fails), it sets a neurosploit/security commit status of failure on the PR head, and it submits a REQUEST_CHANGES review. needs-review findings never trip the gate — only confirmed ones do.

GitHub Enterprise: /integrations setup github and set the API base to your GHE URL (e.g. https://ghe.mycorp.com/api/v3).

3.1 Automations — GitHub Actions

Two workflows ship in examples/github-actions/. Copy them into your repo and add an ANTHROPIC_API_KEY Actions secret (or swap MODEL for a provider you have a key for). The built-in GITHUB_TOKEN already covers commit statuses, reviews and comments.

PR gate — neurosploit-pr-gate.yml Runs on every pull request, reviews the code, and enforces the gate:

neurosploit pr "$REPO" "$PR_NUMBER" --model "$MODEL" --comment --fail-on critical -v

To make it actually block merges: repo Settings → Branches → Branch protection rule on your default branch → Require status checks to pass → select neurosploit-pr-gate. Add Require a pull request review to also honor the REQUEST_CHANGES review it posts.

@neurosploit mention bot — neurosploit-mention.yml Comment @neurosploit on a PR or issue to trigger a scan. Only users with write access can trigger it (a permission check guards the model budget). Everything after the mention is the instruction, in any language:

Comment	Effect
@neurosploit	white-box review of this PR (blocks on critical)
@neurosploit focus SQLi and IDOR	same, steered by the focus
@neurosploit scan https://staging.app	black-box test of that URL
@neurosploit foco em IDOR, fora de escopo /admin	steered review (Portuguese)

The bot reacts 👀 to acknowledge, then posts results back as a comment.

---

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:

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):

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:

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:

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):

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:

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:

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.