diff --git a/.changeset/0185-docs-accuracy-salvage.md b/.changeset/0185-docs-accuracy-salvage.md new file mode 100644 index 0000000..d790055 --- /dev/null +++ b/.changeset/0185-docs-accuracy-salvage.md @@ -0,0 +1,5 @@ +--- +'@cdot65/prisma-airs-sdk': patch +--- + +Docs accuracy fixes: correct the Scan API auth description (API key HMAC and/or bearer token; lowercase `x-pan-token` / `x-payload-hash` headers), fill in the OAuth `TOKEN_ENDPOINT` defaults and EU regional endpoint overrides, replace the fictional `ListingOptions` (`sort`/`filters`) with the real per-service pagination contracts (Management `offset/limit`, Model Security / Red Team `skip/limit/search`, DLP `page/size`), fix Red Team examples (enum casing, `updatePrompt` uses `prompt` not `content`, valid `goal_type`), flesh out the developer vocabulary, and add a Runnable Examples guide page. diff --git a/docs-site/docs/developer/architecture.md b/docs-site/docs/developer/architecture.md index ca7ba77..0e4e85e 100644 --- a/docs-site/docs/developer/architecture.md +++ b/docs-site/docs/developer/architecture.md @@ -17,17 +17,21 @@ The SDK covers four service domains. They split across exactly two authenticatio | Domain | Entry point | Auth | Base URL constant | | -------------- | --------------------- | ------------------------- | ------------------------------- | -| Scan API | `init()` + `Scanner` | API key (HMAC-SHA256) | `DEFAULT_ENDPOINT` | +| Scan API | `init()` + `Scanner` | API key HMAC and/or bearer token | `DEFAULT_ENDPOINT` | | Management API | `ManagementClient` | OAuth2 client_credentials | `DEFAULT_MGMT_ENDPOINT` (+ DLP) | | Model Security | `ModelSecurityClient` | OAuth2 client_credentials | `DEFAULT_MODEL_SEC_*_ENDPOINT` | | Red Team | `RedTeamClient` | OAuth2 client_credentials | `DEFAULT_RED_TEAM_*_ENDPOINT` | -Only the scan service uses the API key. Everything else (management CRUD, DLP, model security, red -teaming) authenticates with OAuth2 client_credentials. The Management client additionally talks to a -separate DLP base URL (`DEFAULT_DLP_ENDPOINT`) reusing the same OAuth credentials. +Only the scan service uses `init()` and the `ApiKeyAuth` adapter. It accepts an API key, a +pre-obtained bearer token, or both; it does not fetch OAuth2 tokens. Everything else (management +CRUD, DLP, model security, red teaming) authenticates with OAuth2 client_credentials. The Management +client additionally talks to a separate DLP base URL (`DEFAULT_DLP_ENDPOINT`) reusing the same OAuth +credentials. All endpoint paths, base URLs, content/batch limits, header names, and retry config live in one -place: [`src/constants.ts`](../reference/api/index.md). A few load-bearing values: +place: +[`src/constants.ts`](https://github.com/cdot65/prisma-airs-sdk/blob/main/src/constants.ts). A few +load-bearing values: ```ts export const MAX_NUMBER_OF_RETRIES = 5; @@ -160,10 +164,20 @@ snapshot (`hasToken`, `isValid`, `isExpired`, `isExpiringSoon`, `expiresInMs`, ` optional `onTokenRefresh` callback fires after each successful refresh. Token-fetch failures throw `AISecSDKException` with `ErrorType.OAUTH_ERROR`. -## Shared listing / pagination +## Listing and pagination shapes -Every list endpoint across the OAuth domains accepts the same base options, defined once in -`src/listing.ts`: +The OAuth domains do not all expose the same pagination contract. The SDK keeps the wire shape close +to each service while sharing helpers where the APIs match: + +- **Management API** resource lists use `offset` / `limit` and return fields such as `next_offset` + where the endpoint supports it. `ProfilesClient.list()` defaults to `offset: 0` and `limit: 100`. +- **Model Security and Red Team** list endpoints use `skip` / `limit` / `search`, defined in + `src/listing.ts` and serialized by the internal `serializeListing()` helper. Sub-clients extend + that base shape with endpoint-specific filters such as Red Team `status` or `target_type`. +- **DLP** list endpoints use Spring-style `page` / `size` options and return `Page` envelopes + from `src/models/dlp-page.ts`. + +The shared Model Security / Red Team base options are: ```ts interface ListingOptions { @@ -173,10 +187,6 @@ interface ListingOptions { } ``` -The internal `serializeListing()` helper turns those into a string-keyed params record. Sub-clients -extend `ListingOptions` with endpoint-specific filters and merge their own params on top of the -serialized base — keeping pagination semantics uniform while allowing per-endpoint filtering. - ## Validation strategy: Zod with `.passthrough()` Validation happens at three distinct boundaries: diff --git a/docs-site/docs/developer/vocabulary.md b/docs-site/docs/developer/vocabulary.md index b53f0cd..eb6477c 100644 --- a/docs-site/docs/developer/vocabulary.md +++ b/docs-site/docs/developer/vocabulary.md @@ -9,7 +9,25 @@ Use these terms exactly when discussing the SDK's design — they have specific ## Domain concepts -Reserved for AIRS domain terms (Scan, Profile, Topic, Job, Target, Custom Attack, EULA, Instance, …). Fill in as decisions crystallize. +- **Scan** — an AI Runtime Security inspection request. Synchronous scans return a verdict inline; + asynchronous scans return a receipt and are later queried by scan or report ID. +- **Security profile** — the named or UUID-addressed AIRS runtime policy referenced by scan calls + and managed through `ManagementClient.profiles`. +- **Custom topic** — a reusable topic guardrails definition managed through `ManagementClient.topics`. +- **DLP resource** — data filtering profiles, data patterns, data profiles, and dictionaries exposed + under `ManagementClient.dlp`. +- **Model Security scan** — a Model Security data-plane scan for model artifacts and related + evaluation, file, label, and violation data. +- **Security group / rule instance** — Model Security management objects that configure which + platform-provided security rules run. Security rules themselves are read-only in the SDK. +- **Target** — an AI Red Teaming management-plane object describing how the service calls the model, + API, or application under test. +- **Scan job** — an AI Red Teaming data-plane run against a target. Jobs are asynchronous and expose + statuses such as `QUEUED`, `RUNNING`, `COMPLETED`, and `FAILED`. +- **Custom attack** — a Red Teaming prompt-set workflow for user-authored prompts, CSV uploads, and + prompt properties. +- **EULA / instance** — Red Teaming management-plane resources for tenant EULA acceptance and + instance, device, and registry-credential management. ## Architecture concepts @@ -24,7 +42,10 @@ interface RequestSpec { path: string; params?: Record; body?: unknown; - responseSchema?: z.ZodType; + contentType?: string; + formData?: FormData; + responseSchema?: z.ZodType; + allowEmptyBody?: boolean; numRetries: number; auth: AuthAdapter; } @@ -65,18 +86,22 @@ A build-time script that diffs Zod schemas in `src/models/` against the authorit ### Listing -A paginated, filterable list request. Owns serialization of `skip` / `limit` / `search` / `sort` / typed filter args into URL search params, and exposes an `async *` iterator (`listAll`) that walks pages. Each list endpoint declares its filter shape; the module owns wire-format mechanics. Replaces ad-hoc per-client query-string building. +A paginated, filterable list request for Model Security and Red Team endpoints that use +`skip` / `limit` / `search`. The internal `serializeListing()` helper turns those fields into URL +search params; individual sub-clients add endpoint-specific filters such as `status`, +`target_type`, or `job_type`. ```ts -interface ListingOptions { +interface ListingOptions { skip?: number; limit?: number; search?: string; - sort?: { field: string; order: 'asc' | 'desc' }; - filters?: TFilters; } ``` +Management API list endpoints use `offset` / `limit`, and DLP endpoints use `page` / `size`, so the +SDK documents those separately instead of forcing every service through `ListingOptions`. + ### RESPONSE_VALIDATION error `AISecSDKException` with `ErrorType.RESPONSE_VALIDATION` is thrown when the backend returns a 2xx with a body that does not match the declared response schema (or is not valid JSON). Distinct from `SERVER_SIDE_ERROR` (5xx) and `CLIENT_SIDE_ERROR` (4xx) so callers can route SDK-bug-vs-backend-bug-vs-client-bug differently. diff --git a/docs-site/docs/getting-started/configuration.mdx b/docs-site/docs/getting-started/configuration.mdx index f89f5ff..f6f488f 100644 --- a/docs-site/docs/getting-started/configuration.mdx +++ b/docs-site/docs/getting-started/configuration.mdx @@ -64,7 +64,7 @@ Falls back to `PANW_MGMT_*` variables if service-specific ones are not set. | `PANW_MODEL_SEC_TSG_ID` | Falls back to MGMT | — | | `PANW_MODEL_SEC_DATA_ENDPOINT` | No | `https://api.sase.paloaltonetworks.com/aims/data` | | `PANW_MODEL_SEC_MGMT_ENDPOINT` | No | `https://api.sase.paloaltonetworks.com/aims/mgmt` | -| `PANW_MODEL_SEC_TOKEN_ENDPOINT` | Falls back to MGMT | — | +| `PANW_MODEL_SEC_TOKEN_ENDPOINT` | Falls back to MGMT | `https://auth.apps.paloaltonetworks.com/oauth2/access_token` | ## Red Team API @@ -78,7 +78,7 @@ Falls back to `PANW_MGMT_*` variables if service-specific ones are not set. | `PANW_RED_TEAM_DATA_ENDPOINT` | No | `https://api.sase.paloaltonetworks.com/ai-red-teaming/data-plane` | | `PANW_RED_TEAM_MGMT_ENDPOINT` | No | `https://api.sase.paloaltonetworks.com/ai-red-teaming/mgmt-plane` | | `PANW_RED_TEAM_NETWORK_BROKER_ENDPOINT` | No | `https://api.sase.paloaltonetworks.com/ai-red-teaming/data-plane/network-broker` | -| `PANW_RED_TEAM_TOKEN_ENDPOINT` | Falls back to MGMT | — | +| `PANW_RED_TEAM_TOKEN_ENDPOINT` | Falls back to MGMT | `https://auth.apps.paloaltonetworks.com/oauth2/access_token` | ## Regional Endpoints @@ -92,6 +92,10 @@ export PANW_AI_SEC_API_ENDPOINT=https://service-sg.api.aisecurity.paloaltonetwor # EU export PANW_MGMT_ENDPOINT=https://api.eu.sase.paloaltonetworks.com/aisec +export PANW_MODEL_SEC_DATA_ENDPOINT=https://api.eu.sase.paloaltonetworks.com/aims/data +export PANW_MODEL_SEC_MGMT_ENDPOINT=https://api.eu.sase.paloaltonetworks.com/aims/mgmt +export PANW_RED_TEAM_DATA_ENDPOINT=https://api.eu.sase.paloaltonetworks.com/ai-red-teaming/data-plane +export PANW_RED_TEAM_MGMT_ENDPOINT=https://api.eu.sase.paloaltonetworks.com/ai-red-teaming/mgmt-plane # UK export PANW_MGMT_ENDPOINT=https://api.uk.sase.paloaltonetworks.com/aisec diff --git a/docs-site/docs/getting-started/environment-variables.mdx b/docs-site/docs/getting-started/environment-variables.mdx index 1b71a9d..ca4292f 100644 --- a/docs-site/docs/getting-started/environment-variables.mdx +++ b/docs-site/docs/getting-started/environment-variables.mdx @@ -38,7 +38,7 @@ All fall back to the corresponding `PANW_MGMT_*` variable if not set. | `PANW_MODEL_SEC_TSG_ID` | `PANW_MGMT_TSG_ID` | — | Tenant Service Group ID | | `PANW_MODEL_SEC_DATA_ENDPOINT` | — | `https://api.sase.paloaltonetworks.com/aims/data` | Data plane base URL | | `PANW_MODEL_SEC_MGMT_ENDPOINT` | — | `https://api.sase.paloaltonetworks.com/aims/mgmt` | Management plane base URL | -| `PANW_MODEL_SEC_TOKEN_ENDPOINT` | `PANW_MGMT_TOKEN_ENDPOINT` | — | OAuth2 token endpoint | +| `PANW_MODEL_SEC_TOKEN_ENDPOINT` | `PANW_MGMT_TOKEN_ENDPOINT` | `https://auth.apps.paloaltonetworks.com/oauth2/access_token` | OAuth2 token endpoint | ## Red Team API @@ -52,7 +52,7 @@ All fall back to the corresponding `PANW_MGMT_*` variable if not set. | `PANW_RED_TEAM_DATA_ENDPOINT` | — | `https://api.sase.paloaltonetworks.com/ai-red-teaming/data-plane` | Data plane base URL | | `PANW_RED_TEAM_MGMT_ENDPOINT` | — | `https://api.sase.paloaltonetworks.com/ai-red-teaming/mgmt-plane` | Management plane base URL | | `PANW_RED_TEAM_NETWORK_BROKER_ENDPOINT` | — | `https://api.sase.paloaltonetworks.com/ai-red-teaming/data-plane/network-broker` | Network broker base URL | -| `PANW_RED_TEAM_TOKEN_ENDPOINT` | `PANW_MGMT_TOKEN_ENDPOINT` | — | OAuth2 token endpoint | +| `PANW_RED_TEAM_TOKEN_ENDPOINT` | `PANW_MGMT_TOKEN_ENDPOINT` | `https://auth.apps.paloaltonetworks.com/oauth2/access_token` | OAuth2 token endpoint | ## Debugging diff --git a/docs-site/docs/guides/examples.mdx b/docs-site/docs/guides/examples.mdx new file mode 100644 index 0000000..286e102 --- /dev/null +++ b/docs-site/docs/guides/examples.mdx @@ -0,0 +1,117 @@ +--- +id: examples +title: Runnable Examples +description: How to run the SDK example scripts for scanning, management, DLP, model security, red teaming, and validation workflows. +--- + +# Runnable Examples + +The repository includes runnable TypeScript examples in `docs-site/examples/`. They exercise the +same public SDK APIs documented in the guides and can be run with `tsx` from the repository root. + +## Setup + +Install dependencies and create an environment file: + +```bash +npm install +cp .env.example .env +``` + +Fill in the credentials required by the workflow you want to run: + +- Scan examples require `PANW_AI_SEC_API_KEY` or `PANW_AI_SEC_API_TOKEN`, plus + `PANW_AI_SEC_PROFILE_NAME`. +- Management examples require `PANW_MGMT_CLIENT_ID`, `PANW_MGMT_CLIENT_SECRET`, and + `PANW_MGMT_TSG_ID`. +- Model Security and Red Team examples can use their service-specific `PANW_MODEL_SEC_*` / + `PANW_RED_TEAM_*` credentials or fall back to `PANW_MGMT_*`. +- Validation scripts marked as mock-backed do not require live AIRS credentials. + +Run examples with: + +```bash +npx tsx --env-file=.env docs-site/examples/