@cdot65/prisma-airs-sdk 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +86 -112
  2. package/dist/index.cjs +1 -1
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +2 -2
  5. package/dist/index.d.ts +2 -2
  6. package/dist/index.js +1 -1
  7. package/dist/index.js.map +1 -1
  8. package/package.json +4 -3
package/README.md CHANGED
@@ -1,6 +1,15 @@
1
1
  # prisma-airs-sdk
2
2
 
3
- TypeScript SDK for Palo Alto Networks **AI Runtime Security (AIRS)**. API-compatible with the official [Python `pan-aisecurity` SDK](https://pypi.org/project/pan-aisecurity/).
3
+ [![CI](https://github.com/cdot65/prisma-airs-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/cdot65/prisma-airs-sdk/actions/workflows/ci.yml)
4
+ [![Tests](https://github.com/cdot65/prisma-airs-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/cdot65/prisma-airs-sdk/actions/workflows/test.yml)
5
+ [![npm version](https://img.shields.io/npm/v/@cdot65/prisma-airs-sdk)](https://www.npmjs.com/package/@cdot65/prisma-airs-sdk)
6
+ [![npm downloads](https://img.shields.io/npm/dm/@cdot65/prisma-airs-sdk)](https://www.npmjs.com/package/@cdot65/prisma-airs-sdk)
7
+ [![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen)](https://github.com/cdot65/prisma-airs-sdk)
8
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6)](https://www.typescriptlang.org/)
9
+ [![Node 18+](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
10
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
11
+
12
+ TypeScript SDK for Palo Alto Networks **Prisma AIRS** — covering the full lifecycle from configuration management to operational scanning across all three service domains: **AI Runtime Security**, **AI Red Teaming**, and **Model Security**.
4
13
 
5
14
  ## Installation
6
15
 
@@ -8,14 +17,26 @@ TypeScript SDK for Palo Alto Networks **AI Runtime Security (AIRS)**. API-compat
8
17
  npm install @cdot65/prisma-airs-sdk
9
18
  ```
10
19
 
11
- Requires Node.js 18+.
20
+ Requires Node.js 18+. Zero external HTTP dependencies (native `fetch` + `crypto`).
21
+
22
+ ## What's Included
23
+
24
+ | Service | Client | Auth | Capabilities |
25
+ | ----------------------- | --------------------- | ------- | ---------------------------------------------------------- |
26
+ | **AI Runtime Security** | `Scanner` | API Key | Sync/async content scanning, prompt injection detection |
27
+ | **Management** | `ManagementClient` | OAuth2 | Security profiles and custom topics CRUD |
28
+ | **Model Security** | `ModelSecurityClient` | OAuth2 | ML model scanning, security groups, rule management |
29
+ | **AI Red Teaming** | `RedTeamClient` | OAuth2 | Automated red team scans, reports, targets, custom attacks |
30
+
31
+ All OAuth2 services share credentials and handle token lifecycle automatically (caching, proactive refresh, 401/403 auto-retry).
12
32
 
13
33
  ## Quick Start
14
34
 
35
+ ### AI Runtime Security — Content Scanning (API Key)
36
+
15
37
  ```ts
16
38
  import { init, Scanner, Content } from '@cdot65/prisma-airs-sdk';
17
39
 
18
- // Initialize (mirrors Python's aisecurity.init())
19
40
  init({ apiKey: 'YOUR_API_KEY' });
20
41
 
21
42
  const scanner = new Scanner();
@@ -30,90 +51,82 @@ console.log(result.category); // "benign" | "malicious"
30
51
  console.log(result.action); // "allow" | "block"
31
52
  ```
32
53
 
33
- ## Initialization
54
+ ### Management — Configuration CRUD (OAuth2)
55
+
56
+ CRUD operations for all three Prisma AIRS services use OAuth2:
34
57
 
35
58
  ```ts
36
- import { init } from '@cdot65/prisma-airs-sdk';
59
+ import { ManagementClient } from '@cdot65/prisma-airs-sdk';
60
+
61
+ const client = new ManagementClient(); // reads PANW_MGMT_* env vars
37
62
 
38
- init({
39
- apiKey: 'your-api-key', // or set PANW_AI_SEC_API_KEY env var
40
- apiToken: 'your-bearer-token', // or set PANW_AI_SEC_API_TOKEN env var
41
- apiEndpoint: 'https://...', // optional, defaults to production
42
- numRetries: 3, // optional, 0-5, default 5
63
+ // Security Profiles
64
+ const profiles = await client.profiles.list();
65
+ const created = await client.profiles.create({
66
+ profile_name: 'my-profile',
67
+ active: true,
68
+ policy: {
69
+ /* ... */
70
+ },
43
71
  });
44
- ```
45
72
 
46
- At least one of `apiKey` or `apiToken` must be provided (directly or via environment variables).
73
+ // Custom Topics
74
+ const topic = await client.topics.create({
75
+ topic_name: 'pii-detector',
76
+ examples: ['SSN: 123-45-6789'],
77
+ });
78
+ ```
47
79
 
48
- ## Scanner Methods
80
+ ### Model Security — ML Model Scanning (OAuth2)
49
81
 
50
- | Method | Description |
51
- | ------------------------------------- | ------------------------------------------ |
52
- | `syncScan(aiProfile, content, opts?)` | Synchronous inline scan |
53
- | `asyncScan(scanObjects)` | Batch async scan (up to 5) |
54
- | `queryByScanIds(scanIds)` | Get results by scan IDs (up to 5) |
55
- | `queryByReportIds(reportIds)` | Get threat reports by report IDs (up to 5) |
82
+ ```ts
83
+ import { ModelSecurityClient } from '@cdot65/prisma-airs-sdk';
56
84
 
57
- ### Sync Scan
85
+ const client = new ModelSecurityClient(); // falls back to PANW_MGMT_* env vars
58
86
 
59
- ```ts
60
- const result = await scanner.syncScan(
61
- { profile_name: 'my-profile' },
62
- new Content({ prompt: 'user input', response: 'model output' }),
63
- {
64
- trId: 'transaction-123',
65
- sessionId: 'session-456',
66
- metadata: { app_name: 'my-app', ai_model: 'gpt-4' },
67
- },
68
- );
87
+ const scans = await client.scans.list({ limit: 10 });
88
+ const groups = await client.securityGroups.list();
89
+ const rules = await client.securityRules.list();
69
90
  ```
70
91
 
71
- ### Async Scan
92
+ ### AI Red Teaming — Automated Testing (OAuth2)
72
93
 
73
94
  ```ts
74
- const result = await scanner.asyncScan([
75
- {
76
- req_id: 1,
77
- scan_req: {
78
- ai_profile: { profile_name: 'my-profile' },
79
- contents: [{ prompt: 'hello', response: 'world' }],
80
- },
81
- },
82
- ]);
83
- ```
95
+ import { RedTeamClient } from '@cdot65/prisma-airs-sdk';
84
96
 
85
- ### Query Results
97
+ const client = new RedTeamClient(); // falls back to PANW_MGMT_* env vars
86
98
 
87
- ```ts
88
- const results = await scanner.queryByScanIds(['scan-uuid-here']);
89
- const reports = await scanner.queryByReportIds(['report-id-here']);
99
+ const scans = await client.scans.list({ limit: 5 });
100
+ const targets = await client.targets.list();
101
+ const categories = await client.scans.getCategories();
90
102
  ```
91
103
 
92
- ## Content Class
104
+ ## Authentication
93
105
 
94
- ```ts
95
- import { Content } from '@cdot65/prisma-airs-sdk';
96
-
97
- const content = new Content({
98
- prompt: 'user prompt',
99
- response: 'model response',
100
- context: 'grounding context',
101
- codePrompt: 'code input',
102
- codeResponse: 'code output',
103
- toolEvent: {
104
- metadata: { ecosystem: 'mcp', method: 'invoke', server_name: 'my-server' },
105
- input: '{"query": "test"}',
106
- },
107
- });
106
+ | Auth Method | Used By |
107
+ | ------------------------------- | ----------------------------------------------------------- |
108
+ | **API Key** (HMAC-SHA256) | AI Runtime Security scans only |
109
+ | **OAuth2** (client_credentials) | Everything else — Management CRUD, Red Team, Model Security |
108
110
 
109
- // Serialize
110
- const json = content.toJSON();
111
+ ```bash
112
+ # AI Runtime Security scans
113
+ export PANW_AI_SEC_API_KEY=your-api-key
111
114
 
112
- // Deserialize
113
- const restored = Content.fromJSON(json);
114
- const fromFile = Content.fromJSONFile('./content.json');
115
+ # OAuth2 (shared by Management, Red Team, Model Security)
116
+ export PANW_MGMT_CLIENT_ID=your-client-id
117
+ export PANW_MGMT_CLIENT_SECRET=your-client-secret
118
+ export PANW_MGMT_TSG_ID=1234567890
115
119
  ```
116
120
 
121
+ ## Scanner Methods
122
+
123
+ | Method | Description |
124
+ | ------------------------------------- | ------------------------------------------ |
125
+ | `syncScan(aiProfile, content, opts?)` | Synchronous inline scan |
126
+ | `asyncScan(scanObjects)` | Batch async scan (up to 5) |
127
+ | `queryByScanIds(scanIds)` | Get results by scan IDs (up to 5) |
128
+ | `queryByReportIds(reportIds)` | Get threat reports by report IDs (up to 5) |
129
+
117
130
  ## Error Handling
118
131
 
119
132
  ```ts
@@ -123,65 +136,26 @@ try {
123
136
  await scanner.syncScan(profile, content);
124
137
  } catch (err) {
125
138
  if (err instanceof AISecSDKException) {
126
- console.error(err.message); // includes ErrorType prefix
127
- console.error(err.errorType); // ErrorType enum value
139
+ console.error(err.message);
140
+ console.error(err.errorType);
128
141
  }
129
142
  }
130
143
  ```
131
144
 
132
145
  Error types: `SERVER_SIDE_ERROR`, `CLIENT_SIDE_ERROR`, `USER_REQUEST_PAYLOAD_ERROR`, `MISSING_VARIABLE`, `AISEC_SDK_ERROR`, `OAUTH_ERROR`.
133
146
 
134
- ## Management API
135
-
136
- Separate client for CRUD operations on Security Profiles and Custom Topics via OAuth2 client credentials. See [docs/management-api.md](docs/management-api.md) for full details.
137
-
138
- ```bash
139
- # Required env vars (or pass as constructor options)
140
- export PANW_MGMT_CLIENT_ID=your-client-id
141
- export PANW_MGMT_CLIENT_SECRET=your-client-secret
142
- export PANW_MGMT_TSG_ID=1234567890
143
- # Optional: override for EU/UK/FedRAMP
144
- # export PANW_MGMT_ENDPOINT=https://api.eu.sase.paloaltonetworks.com/aisec
145
- ```
146
-
147
- ```ts
148
- import { ManagementClient } from '@cdot65/prisma-airs-sdk';
149
-
150
- const client = new ManagementClient();
151
-
152
- // Security Profiles
153
- const profiles = await client.profiles.list();
154
- const created = await client.profiles.create({ profile_name: 'my-profile', active: true, policy: { ... } });
155
- await client.profiles.update(created.profile_id, { ... });
156
- await client.profiles.delete(created.profile_id);
157
-
158
- // Custom Topics
159
- const topics = await client.topics.list();
160
- const topic = await client.topics.create({ topic_name: 'pii-detector', examples: ['SSN: 123-45-6789'] });
161
- await client.topics.update(topic.topic_id, { ... });
162
- await client.topics.delete(topic.topic_id);
163
- await client.topics.forceDelete(topic.topic_id); // even if referenced by a profile
164
- ```
165
-
166
- ## Migration from v0.1
147
+ ## Documentation
167
148
 
168
- | v0.1 | v0.2 |
169
- | --------------------------------------- | --------------------------------------------- |
170
- | `new PrismaAirsSdkClient({ apiToken })` | `init({ apiKey }); new Scanner()` |
171
- | `client.scanSyncRequest(body)` | `scanner.syncScan(aiProfile, content, opts?)` |
172
- | `client.scanAsyncRequest(body)` | `scanner.asyncScan(scanObjects)` |
173
- | `client.getScanResultsByScanIds(ids)` | `scanner.queryByScanIds(ids)` |
174
- | `client.getThreatScanReports(ids)` | `scanner.queryByReportIds(ids)` |
175
- | `PrismaAirsApiError` | `AISecSDKException` |
176
- | `axios` dependency | Native `fetch` (zero HTTP deps) |
149
+ Full documentation at **[cdot65.github.io/prisma-airs-sdk](https://cdot65.github.io/prisma-airs-sdk/)** — includes API reference, service guides, OAuth lifecycle docs, and examples.
177
150
 
178
151
  ## Development
179
152
 
180
153
  ```bash
181
154
  npm install
182
- npm run build # tsup (CJS + ESM + .d.ts)
183
- npm run test # vitest
184
- npm run lint # eslint
155
+ npm run build # tsup (CJS + ESM + .d.ts)
156
+ npm run test # vitest (617 tests, 99%+ coverage)
157
+ npm run lint # eslint
158
+ npm run typecheck # tsc --noEmit
185
159
  ```
186
160
 
187
161
  ## License
package/dist/index.cjs CHANGED
@@ -362,7 +362,7 @@ var MAX_NUMBER_OF_BATCH_SCAN_OBJECTS = 5;
362
362
  var MAX_CONNECTION_POOL_SIZE = 100;
363
363
  var MAX_NUMBER_OF_RETRIES = 5;
364
364
  var HTTP_FORCE_RETRY_STATUS_CODES = [500, 502, 503, 504];
365
- var SDK_VERSION = "0.5.0";
365
+ var SDK_VERSION = "0.5.2";
366
366
  var USER_AGENT = `PAN-AIRS/${SDK_VERSION}-typescript-sdk`;
367
367
  var DEFAULT_MGMT_ENDPOINT = "https://api.sase.paloaltonetworks.com/aisec";
368
368
  var DEFAULT_TOKEN_ENDPOINT = "https://auth.apps.paloaltonetworks.com/oauth2/access_token";