524 lines
11 KiB
Markdown
524 lines
11 KiB
Markdown
# AttackTracer Ninja V2 Repo Plan
|
|
|
|
## Purpose
|
|
|
|
This document turns the V2 architecture into a concrete repository refactor plan.
|
|
|
|
It answers:
|
|
|
|
- which existing components should be removed or deprecated
|
|
- which new components should be created
|
|
- how the client package should be structured
|
|
- what the n8n webhook contract should look like
|
|
- in which order the migration should happen
|
|
|
|
## Target result
|
|
|
|
The repository should end up centered around one endpoint client package that:
|
|
|
|
- runs on every managed Windows device
|
|
- writes NinjaOne device fields locally
|
|
- uploads signed JSON reports to n8n
|
|
- can be installed and updated from NinjaOne using GitLab-hosted release artifacts
|
|
|
|
The repository should no longer rely on:
|
|
|
|
- share mirroring
|
|
- a central `AttackTracerNinjaServer`
|
|
- organization aggregation on a Windows endpoint
|
|
|
|
## Existing components to remove or deprecate
|
|
|
|
## Remove from active architecture
|
|
|
|
These should be retired from the primary product path:
|
|
|
|
- `scripts/build-attacktracer-org-report.ps1`
|
|
- `installer/runtime-build-attacktracer-org-report.ps1`
|
|
- `scripts/run-attacktracer-ninja-server.ps1`
|
|
- `installer/runtime-run-attacktracer-ninja-server.ps1`
|
|
- `scripts/build-attacktracer-server-installer.ps1`
|
|
- `installer/server-install-attacktracer-ninja-server.ps1`
|
|
- `installer/server-uninstall-attacktracer-ninja-server.ps1`
|
|
- `installer/AttackTracerNinjaServerBootstrapper/*`
|
|
- `docs/attacktracer-ninja-server.md`
|
|
- share-based org-report playbook content in `docs/ninjaone-org-report-playbook.md`
|
|
|
|
## Keep only as legacy reference
|
|
|
|
These can remain temporarily during migration but should be clearly marked legacy:
|
|
|
|
- `scripts/run-attacktracer-ninja-monitor.ps1`
|
|
- `scripts/run-attacktracer-ninja.ps1`
|
|
- `docs/ninjaone-monitoring-playbook.md`
|
|
- `config/attacktracer-settings.example.json`
|
|
|
|
## Existing components to preserve and refactor
|
|
|
|
These are still valuable and should become the base for V2:
|
|
|
|
- `src/AttackTracerNinjaCli/AttackScanner.cs`
|
|
- `src/AttackTracerNinjaCli/VulnerabilityCorrelation.cs`
|
|
- `src/AttackTracerNinjaCli/Models.cs`
|
|
- `src/AttackTracerNinjaCli/JsonOptions.cs`
|
|
- `src/AttackTracerNinjaCli/Program.cs`
|
|
- `src/AttackTracerNinjaCli/ScanOptions.cs`
|
|
|
|
Core scanning logic should remain in C#.
|
|
|
|
## New repository structure
|
|
|
|
Recommended target layout:
|
|
|
|
```text
|
|
src/
|
|
AttackTracerNinjaCli/
|
|
AttackTracerNinjaCli.csproj
|
|
Commands/
|
|
ScanCommand.cs
|
|
UploadCommand.cs
|
|
ScanAndUploadCommand.cs
|
|
VersionCommand.cs
|
|
Security/
|
|
HmacSigner.cs
|
|
NonceStore.cs
|
|
ProtectedSecretStore.cs
|
|
Transport/
|
|
N8nUploadClient.cs
|
|
UploadEnvelopeBuilder.cs
|
|
Models/
|
|
ReportEnvelope.cs
|
|
ScanReport.cs
|
|
UploadResult.cs
|
|
Configuration/
|
|
ClientConfiguration.cs
|
|
ConfigurationLoader.cs
|
|
|
|
scripts/
|
|
install-attacktracer-ninja.ps1
|
|
uninstall-attacktracer-ninja.ps1
|
|
update-attacktracer-ninja.ps1
|
|
run-attacktracer-ninja.ps1
|
|
publish-ninja-fields.ps1
|
|
|
|
config/
|
|
attacktracer-client.example.json
|
|
update-channel.example.json
|
|
|
|
docs/
|
|
attacktracer-ninja-v2-architecture.md
|
|
attacktracer-ninja-v2-repo-plan.md
|
|
attacktracer-ninja-v2-n8n-contract.md
|
|
attacktracer-ninja-v2-deployment.md
|
|
|
|
build/
|
|
build-client-package.ps1
|
|
build-release-manifest.ps1
|
|
|
|
samples/
|
|
webhook-payload.example.json
|
|
version.example.json
|
|
```
|
|
|
|
## New endpoint client responsibilities
|
|
|
|
## Binary responsibilities
|
|
|
|
The compiled client should do these jobs:
|
|
|
|
- local attack scanning
|
|
- vulnerability correlation
|
|
- JSON report generation
|
|
- report signing
|
|
- authenticated upload to n8n
|
|
- stable exit codes
|
|
- machine-readable output for NinjaOne wrappers
|
|
|
|
## Wrapper responsibilities
|
|
|
|
PowerShell wrappers should only do:
|
|
|
|
- install/uninstall
|
|
- update
|
|
- local config bootstrap
|
|
- invoking the binary
|
|
- publishing NinjaOne device custom fields
|
|
- logging wrapper-level failures
|
|
|
|
## New client command model
|
|
|
|
Recommended commands:
|
|
|
|
### `scan`
|
|
|
|
Performs local scan and writes a report file.
|
|
|
|
Example:
|
|
|
|
```powershell
|
|
AttackTracerNinjaCli.exe scan --output "C:\ProgramData\AttackTracerNinja\reports\latest.json" --ninja-output
|
|
```
|
|
|
|
### `upload`
|
|
|
|
Uploads an existing report to n8n.
|
|
|
|
Example:
|
|
|
|
```powershell
|
|
AttackTracerNinjaCli.exe upload --report "C:\ProgramData\AttackTracerNinja\reports\latest.json"
|
|
```
|
|
|
|
### `scan-and-upload`
|
|
|
|
Performs a scan and directly uploads the result.
|
|
|
|
Example:
|
|
|
|
```powershell
|
|
AttackTracerNinjaCli.exe scan-and-upload --output "C:\ProgramData\AttackTracerNinja\reports\latest.json" --ninja-output
|
|
```
|
|
|
|
### `version`
|
|
|
|
Prints installed version and build metadata.
|
|
|
|
## Config model
|
|
|
|
Recommended local config file:
|
|
|
|
- `C:\ProgramData\AttackTracerNinja\config\attacktracer-client.json`
|
|
|
|
Recommended fields:
|
|
|
|
```json
|
|
{
|
|
"schemaVersion": "2.0",
|
|
"environment": "production",
|
|
"lookbackDays": 7,
|
|
"topFindings": 10,
|
|
"n8nWebhookUrl": "https://n8n.example.com/webhook/attacktracer-ingest",
|
|
"deviceIdentifierMode": "machineName",
|
|
"uploadTimeoutSeconds": 30,
|
|
"enableVulnerabilityCorrelation": true,
|
|
"vulnerabilityCsvPath": "",
|
|
"secretReference": "device-default"
|
|
}
|
|
```
|
|
|
|
Secrets should not be stored here in clear text.
|
|
|
|
## Local secret handling plan
|
|
|
|
## Secret storage
|
|
|
|
Create a protected local secret file under:
|
|
|
|
- `C:\ProgramData\AttackTracerNinja\secrets\upload-secret.dat`
|
|
|
|
Use DPAPI machine protection to encrypt the secret.
|
|
|
|
## Secret bootstrap
|
|
|
|
Initial rollout options:
|
|
|
|
1. NinjaOne install task writes a tenant token once and immediately protects it with DPAPI.
|
|
2. Later evolution: unique per-device secret issued centrally.
|
|
|
|
Recommended first cut:
|
|
|
|
- tenant-level ingest secret wrapped with DPAPI
|
|
- HMAC signature over request metadata + payload hash
|
|
|
|
## n8n webhook contract
|
|
|
|
## Endpoint request
|
|
|
|
Method:
|
|
|
|
- `POST`
|
|
|
|
URL:
|
|
|
|
- provided via config, for example:
|
|
- `https://n8n.example.com/webhook/attacktracer-ingest`
|
|
|
|
Headers:
|
|
|
|
- `Content-Type: application/json`
|
|
- `X-ATN-Device`
|
|
- `X-ATN-Timestamp`
|
|
- `X-ATN-Nonce`
|
|
- `X-ATN-Version`
|
|
- `X-ATN-Payload-SHA256`
|
|
- `X-ATN-Signature`
|
|
|
|
Body:
|
|
|
|
- JSON scan report only
|
|
|
|
Signature input recommendation:
|
|
|
|
```text
|
|
device + "\n" + timestamp + "\n" + nonce + "\n" + version + "\n" + payloadSha256
|
|
```
|
|
|
|
Algorithm:
|
|
|
|
- `HMAC-SHA256`
|
|
|
|
## n8n validation rules
|
|
|
|
n8n should reject when:
|
|
|
|
- any required header is missing
|
|
- timestamp is outside tolerance
|
|
- nonce already exists
|
|
- payload hash mismatches body
|
|
- signature mismatches
|
|
- schema is invalid
|
|
|
|
## Suggested report payload schema
|
|
|
|
```json
|
|
{
|
|
"schemaVersion": "2.0",
|
|
"machineName": "WSUS",
|
|
"generatedAtUtc": "2026-07-16T19:12:00Z",
|
|
"clientVersion": "2.0.0",
|
|
"baseStatus": "ok",
|
|
"alertState": "ok",
|
|
"totalEvents": 0,
|
|
"uniqueIpCount": 0,
|
|
"errorCount": 0,
|
|
"attackFindings": [],
|
|
"vulnerabilityCorrelation": {
|
|
"totalCount": 0,
|
|
"criticalCount": 0,
|
|
"highCvssCount": 0
|
|
},
|
|
"runtime": {
|
|
"startedAtUtc": "2026-07-16T19:11:57Z",
|
|
"finishedAtUtc": "2026-07-16T19:12:00Z",
|
|
"uploadAttempted": true
|
|
}
|
|
}
|
|
```
|
|
|
|
## GitLab release plan
|
|
|
|
## Release artifacts
|
|
|
|
Each release should publish:
|
|
|
|
- `AttackTracerNinjaClient-win-x64.zip`
|
|
- `AttackTracerNinjaClient-win-x64.zip.sha256`
|
|
- `version.json`
|
|
|
|
## ZIP layout
|
|
|
|
```text
|
|
AttackTracerNinjaClient-win-x64.zip
|
|
app/
|
|
AttackTracerNinjaCli.exe
|
|
AttackTracerNinjaCli.dll
|
|
scripts/
|
|
install-attacktracer-ninja.ps1
|
|
uninstall-attacktracer-ninja.ps1
|
|
update-attacktracer-ninja.ps1
|
|
run-attacktracer-ninja.ps1
|
|
publish-ninja-fields.ps1
|
|
config/
|
|
attacktracer-client.example.json
|
|
VERSION.txt
|
|
```
|
|
|
|
## Manifest format
|
|
|
|
```json
|
|
{
|
|
"channel": "stable",
|
|
"version": "2.0.0",
|
|
"artifactUrl": "https://gitlab.example.com/group/project/-/releases/v2.0.0/downloads/AttackTracerNinjaClient-win-x64.zip",
|
|
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
|
"publishedAtUtc": "2026-07-16T19:15:00Z"
|
|
}
|
|
```
|
|
|
|
## NinjaOne task model
|
|
|
|
## Task A: install/update client
|
|
|
|
Runs as SYSTEM.
|
|
|
|
Responsibilities:
|
|
|
|
- fetch `version.json`
|
|
- compare with local version
|
|
- download artifact when newer
|
|
- verify SHA-256
|
|
- verify Authenticode signature on executable
|
|
- install or update package
|
|
|
|
## Task B: run scan
|
|
|
|
Runs as SYSTEM on each endpoint.
|
|
|
|
Responsibilities:
|
|
|
|
- invoke `run-attacktracer-ninja.ps1`
|
|
- publish device custom fields
|
|
- trigger upload to n8n
|
|
|
|
## Device custom field path
|
|
|
|
Keep the current device-level field strategy.
|
|
|
|
Wrappers should continue using:
|
|
|
|
- `Ninja-Property-Set` when available
|
|
- Ninja CLI fallback if needed
|
|
|
|
Fields to preserve:
|
|
|
|
- `attacktracerstatus`
|
|
- `attacktracerreason`
|
|
- `attacktracerbasestatus`
|
|
- `attacktracerevents`
|
|
- `attacktraceruniqueips`
|
|
- `attacktracercvecritical`
|
|
- `attacktracercvetotal`
|
|
- `attacktracermode`
|
|
- `attacktracertriggered`
|
|
- `attacktracerlastscanutc`
|
|
|
|
## Concrete code refactor plan
|
|
|
|
## Step 1: isolate scan model
|
|
|
|
Refactor current CLI so scan output is represented by one stable report class.
|
|
|
|
Create:
|
|
|
|
- `Models/ScanReport.cs`
|
|
|
|
Move report shape ownership there.
|
|
|
|
## Step 2: add transport layer
|
|
|
|
Create:
|
|
|
|
- `Transport/N8nUploadClient.cs`
|
|
- `Transport/UploadEnvelopeBuilder.cs`
|
|
|
|
Responsibilities:
|
|
|
|
- prepare headers
|
|
- hash payload
|
|
- sign request
|
|
- upload with timeout and retry policy
|
|
|
|
## Step 3: add secret protection
|
|
|
|
Create:
|
|
|
|
- `Security/ProtectedSecretStore.cs`
|
|
|
|
Responsibilities:
|
|
|
|
- store secret using DPAPI
|
|
- load secret at runtime
|
|
|
|
## Step 4: add nonce/replay support
|
|
|
|
Create:
|
|
|
|
- `Security/NonceStore.cs`
|
|
|
|
Local nonce history is optional, but useful for diagnostics.
|
|
|
|
## Step 5: split commands
|
|
|
|
Refactor `Program.cs` into command-oriented classes:
|
|
|
|
- `ScanCommand.cs`
|
|
- `UploadCommand.cs`
|
|
- `ScanAndUploadCommand.cs`
|
|
- `VersionCommand.cs`
|
|
|
|
## Step 6: simplify wrappers
|
|
|
|
Replace older server/share assumptions in wrappers.
|
|
|
|
`run-attacktracer-ninja.ps1` should become:
|
|
|
|
- invoke binary
|
|
- capture output
|
|
- write Ninja device fields
|
|
- exit with monitoring-friendly code
|
|
|
|
## Step 7: replace build pipeline
|
|
|
|
Create:
|
|
|
|
- `build/build-client-package.ps1`
|
|
- `build/build-release-manifest.ps1`
|
|
|
|
Deprecate:
|
|
|
|
- heavy installer-first flow if ZIP distribution is enough
|
|
|
|
## Step 8: deprecate server package
|
|
|
|
Mark these as legacy and remove from active release build:
|
|
|
|
- `AttackTracerNinjaServer*`
|
|
- org HTML writer logic
|
|
- share mirroring flow
|
|
|
|
## Implementation order
|
|
|
|
## Phase A: repo cleanup and design freeze
|
|
|
|
1. Mark server/share docs as legacy
|
|
2. Add new config and payload docs
|
|
3. Freeze V2 JSON schema
|
|
|
|
## Phase B: client refactor
|
|
|
|
1. Add command split
|
|
2. Add signed upload path
|
|
3. Add DPAPI secret handling
|
|
4. Keep existing scan logic intact
|
|
|
|
## Phase C: packaging
|
|
|
|
1. Build ZIP package
|
|
2. Build version manifest
|
|
3. Add install/update scripts
|
|
|
|
## Phase D: central integration
|
|
|
|
1. Build n8n ingest workflow
|
|
2. Build Postgres schema
|
|
3. Build NinjaOne org-field update workflow
|
|
|
|
## Phase E: rollout
|
|
|
|
1. Pilot group
|
|
2. Validate cadence and missing-report detection
|
|
3. Roll out widely
|
|
4. Retire server/share path
|
|
|
|
## Final recommendation
|
|
|
|
Implement V2 as:
|
|
|
|
- compiled endpoint collector
|
|
- PowerShell operational wrapper
|
|
- GitLab-hosted signed releases
|
|
- NinjaOne-based deployment and update
|
|
- n8n-based central ingestion and org aggregation
|
|
|
|
This gives a cleaner codebase and a safer operational model than extending the old share/server architecture further.
|