# neo-tools — complete library (all audiences)

_Generated whole-library download. See `agent-manifest.json` → `library` for discovery._

## Table of contents

- **Overview** (`00-overview`, developers)
- **Local development** (`01-local-dev`, developers)
- **Production boundary** (`02-production`, developers)
- **Status UI** (`03-status-ui`, developers)

---

# Overview — developers

# Overview — Developers

**Audience:** Engineers orienting on the neo-tools connector monorepo.  
**Related:** [Local development](../01-local-dev/developers/BOOK.md) · [Production boundary](../02-production/developers/BOOK.md)

---

## 1. What neo-tools is

Monorepo of Neo pipeline **connector workers** under the `@neo-connectors` scope. Each package is a standalone HTTP worker that the Memorix pipeline registry invokes. Workers talk to vendor APIs (live) or **`@x12i/api-simulator`** (simulation) and optionally persist through Memorix Explorer.

Packages live in role folders (`iam/`, `network-security/`, `edr-xdr/`, `vulnerability-management/`, `siem/`, `platform/`). npm package names stay `@neo-connectors/*`. Packages do not import each other’s business logic. Cross-domain linkage (for example firewall ↔ XDR) is via shared fixture / asset IDs and `@neo-connectors/neo-evidence-kit`. There are no Docker/k8s manifests in this repo.

---

## 2. Packages and ports

| Package | Path | Role | Port |
|---------|------|------|------|
| `neo-services-firewall-topology` | `network-security/` | Firewall topology | `9201` |
| `neo-firewall-simulator` | `network-security/` | Firewall simulator | `9251` |
| `neo-cortex-xdr-services` | `edr-xdr/` | Cortex XDR | `9501` |
| `neo-xdr-simulator` | `edr-xdr/` | XDR simulator | `9551` |
| `neo-crowdstrike-falcon-services` | `edr-xdr/` | CrowdStrike | `9901` |
| `neo-crowdstrike-simulator` | `edr-xdr/` | CrowdStrike simulator | `9951` |
| `neo-tenable-nessus-services` | `vulnerability-management/` | Nessus | `9601` |
| `neo-tenable-nessus-simulator` | `vulnerability-management/` | Nessus simulator | `9651` |
| `neo-microsoft-entra-identities-services` | `iam/` | Entra ID | `9701` |
| `neo-entra-simulator` | `iam/` | Entra simulator | `9751` |
| `neo-credorix-simulator` | `iam/` | Credorix lease simulator | `9252` |
| `neo-splunk-platform-services` | `siem/` | Splunk | `9801` |
| `neo-splunk-simulator` | `siem/` | Splunk simulator | `9851` |
| `neo-status-ui` | `platform/` | Local status dashboard | `9001` |

Libraries (no HTTP port): `@neo-connectors/credorix-access`, `@neo-connectors/mgc-definitions`, `@neo-connectors/neo-evidence-kit`.

---

## 3. HTTP contract

Every worker exposes:

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/health` | Process liveness |
| `GET` | `/ready` | Config readiness (no vendor probes) |
| `GET` | `/_live` | Embeddable live request view (`@x12i/api-live-view`) |
| `GET` | `/metadata` | Identity + skills + runtime coords |
| `GET` | `/capabilities` | Declared connector capabilities |
| `POST` | `/pipeline` | Pipeline invoke; token required in prod |

Requests carry `x-correlation-id`. Startup logs print `origin · health · live · metadata`.

Platform touchpoints include `@x12i/memorix-pipeline-services`, `@x12i/api-simulator`, Memorix Explorer, Catalox write descriptors, and Credorix for live credential leases.

---

## 4. Where to go next

1. **Local development** — `npm run dev`, simulators, knowledge pack CLIs.
2. **Production boundary** — `SERVICE_MODE`, internal token, supported deployments.
3. **Status UI** — discovery vs seed inventory at `:9001`.
4. Platform docs — `npm run docs:memorix`, `docs:simulator`, `docs:docify` from the repo root.

---

# Local development — developers

# Local development — Developers

**Audience:** Engineers running neo-tools on a laptop.  
**Related:** [Overview](../00-overview/developers/BOOK.md) · [Status UI](../03-status-ui/developers/BOOK.md)

---

## 1. Install

Requires Node.js **20+**.

```bash
npm install
```

Copy `.env.example` as needed for local Credorix / Explorer / vendor settings. `npm run dev` sets `SERVICE_MODE=dev`.

---

## 2. Run dev

```bash
npm run dev
```

Starts connector workers, package simulators, and the status dashboard together. Open [http://127.0.0.1:9001](http://127.0.0.1:9001). Ctrl+C stops every process.

Per-tool scripts:

| Script | Role |
|--------|------|
| `npm run <tool>:dev` | Worker in `SERVICE_MODE=dev` |
| `npm run <tool>:sim` | Package simulator HTTP service |
| `npm run <tool>:serve` | Worker production-style entry |
| `npm run status:dev` | Status UI alone |

---

## 3. Package simulators

Each vendor ships `@neo-connectors/<vendor>-simulator` that owns fixtures and `@x12i/api-simulator` logic.

- Workers dispatch stubs **in-process** via the simulator package.
- `npm run <tool>:sim` binds the same simulator over HTTP with its own `/health` + `/_live` (typically worker port + 50).

Contracts we follow from `@x12i/api-simulator-docs`: `ship-package-simulator`, `expose-node-service`.

---

## 4. Knowledge pack CLIs

Root installs product knowledge SDKs as **devDependencies only**:

| CLI | Package |
|-----|---------|
| `npm run docs:neo-tools` | `@neo-connectors/neo-tools-docs` (this library) |
| `npm run docs:memorix` | `@x12i/memorix-docs` |
| `npm run docs:simulator` | `@x12i/api-simulator-docs` |
| `npm run docs:docify` | `@x12i/docify` (platform orientation) |

Examples:

```bash
npm run docs:neo-tools -- list-use-cases
npm run docs:neo-tools -- use-case run-local-stack
npm run docs:memorix -- use-case http-process-compliance
npm run docs:simulator -- use-case ship-package-simulator
```

Human site for this library: `npm run docs -w @neo-connectors/neo-tools-docs`.

---

# Production boundary — developers

# Production boundary — Developers

**Audience:** Engineers deploying connector workers.  
**Related:** [Overview](../00-overview/developers/BOOK.md) · repo `docs/production.md` · `docs/credorix-connection.md`

---

## 1. Verdict

Workers are production-ready within a **single-host** deployment or a **private multi-host** deployment on a trusted internal network or VPN.

Production-safe behavior is the default. Development behavior must be explicitly enabled with `SERVICE_MODE=dev`.

Production mode rejects stub providers, demo/placeholder credentials, unsafe in-memory data-plane fallbacks, and missing `INTERNAL_SERVICE_TOKEN`. Mutating and scheduled work must have a **single active owner**. Workers do **not** provide distributed coordination.

---

## 2. Runtime modes

| `SERVICE_MODE` | Behavior |
|----------------|----------|
| `dev` | Development: stubs, in-memory data plane, optional internal token |
| `prod` | Production gates enforced |
| missing | Same as `prod` |
| any other value | Startup failure |

Do not add modes such as `test`, `local`, `demo`, `staging`, or `sandbox`. Staging should run in `prod` mode.

**Required in prod:** `INTERNAL_SERVICE_TOKEN` — sent as `Authorization: Bearer …` or `x-internal-service-token` on `POST /pipeline`.

| Route | Auth in prod |
|-------|--------------|
| `GET /health`, `/ready`, `/metadata`, `/capabilities` | Open |
| `POST /pipeline` | Internal token required |

---

## 3. Supported vs unsupported

**Supported**

- Single machine: workers, registry, persistence, and status UI may co-exist
- Private multi-host / VPN: ports must not be public; one active owner for mutating work

**Unsupported**

- Public internet exposure
- Multi-region / HA / active-active mutating workers
- Distributed locks or leader election
- Public webhooks / customer-facing auth
- Application-managed cloud KMS / workload identity

**Deployment-owned:** network isolation, credential injection, TLS across machines, backups, monitoring, process restart.

`neo-status-ui` is a discovery surface. In `prod`, **Try is disabled**. Never put `INTERNAL_SERVICE_TOKEN` in browser-side code.

---

## 4. Credorix live unlock

Live vendor calls are **Credorix-first** (lease/broker by `credentialRef` / `tokenRef`). Process env remains an optional local fallback via `@neo-connectors/credorix-access`.

Typical flow: BFF/pipeline passes ids only → worker uses `CREDORIX_*` → Credorix leases → vendor. See repo `docs/credorix-connection.md` for caller registration and consent notes.

Outbound provider and Explorer calls use per-package request timeout env vars. No operation should wait forever.

---

# Status UI — developers

# Status UI — Developers

**Audience:** Engineers using or extending the local discovery dashboard.  
**Related:** [Local development](../01-local-dev/developers/BOOK.md) · repo `docs/discovery-status-ui-methodology.md` · `docs/service-status-ui-guidelines.md`

---

## 1. Two planes

Split **runtime** from **declared inventory**. Mixing them on one scrolling page hides both answers.

| Plane | Question | Data |
|-------|----------|------|
| **Runtime / services** | Are processes up? What can they do now? | Live probes |
| **Metadata / seeds** | What should be registered? Has it been applied? | Pack files + optional ledger |

Give each plane its own primary view (tab). Reference app: `neo-status-ui` at `http://127.0.0.1:9001`.

---

## 2. Services tab

**Job:** discovery and smoke against live workers.

Workers are the source of truth. The UI must **not** hardcode skill catalogs.

| Endpoint | Role |
|----------|------|
| `GET /health` | On / off |
| `GET /metadata` | Endpoints + skills (+ access / consent hints) |
| `GET /capabilities` | Optional capability declaration |
| `POST /pipeline` via server proxy | **Dev-only** Try playground |

Browsers must not call worker ports directly (CORS). Aggregate via status UI proxy routes. In `SERVICE_MODE=prod`, Try returns 403.

---

## 3. Seeds tab

**Job:** expected Catalox / package-seed inventory vs optional applied ledger.

Pack files on disk are the source of truth for expected inventory. Live “is seeded?” needs Mongo (or equivalent) and can degrade gracefully when unavailable.

`npm run seed:status` reports expected vs applied for the Seeds tab.

---

## 4. Adding a worker

1. Implement `/health`, `/_live`, `/metadata` (with `skills[]` + `runtime`), `/pipeline`.
2. Ship `@neo-connectors/<vendor>-simulator` (+ HTTP on workerPort+50) and register both in `platform/neo-status-ui/src/status.ts`.
3. Document env defaults in status UI README, root README, and `.env.example`.
4. Wire `npm run <tool>:dev`, `npm run <tool>:sim`, and the root `dev` concurrently line.
5. Verify: `:9001` → expand → SIM ON · Worker `/_live` · Simulator `/_live` → Try → Stub → Send.