/ api_ja.md
api_ja.md
1 # A.I.G API ドキュメント 2 3 4 ## 概要 5 6 A.I.G（AI-Infra-Guard）は、Agent Scan、MCPサーバースキャン、ジェイルブレイク評価、AIインフラスキャン、およびモデル構成管理のための包括的なAPIインターフェースを提供します。本ドキュメントでは、各APIインターフェースの使用方法、パラメータの説明、およびサンプルコードについて詳しく説明します。 7 8 プロジェクト起動後、`http://localhost:8088/docs/index.html` にアクセスしてSwaggerドキュメントを閲覧できます。 9 10 ## 目次 11 12 ### 基本インターフェース 13 - ファイルアップロードインターフェース 14 - タスク作成インターフェース 15 16 ### タスクタイプ 17 1. Agent Scan API 18 2. MCPサーバースキャン API 19 3. ジェイルブレイク評価 API 20 4. AIインフラスキャン API 21 22 ### モデル管理 API 23 1. モデル一覧取得 24 2. モデル詳細取得 25 3. モデル作成 26 4. モデル更新 27 5. モデル削除 28 6. YAML設定モデル 29 30 ### タスクステータス照会 31 - タスクステータス取得 32 - タスク結果取得 33 34 ### 完全なワークフロー例 35 - MCPソースコードスキャンの完全なワークフロー 36 - ジェイルブレイク評価の完全なワークフロー 37 38 ## 基本情報 39 40 - **ベースURL**: `http://localhost:8088`（実際のデプロイに応じて調整してください） 41 - **Content-Type**: `application/json` 42 - **認証**: リクエストヘッダーを通じて認証情報を渡します 43 44 ## 共通レスポンス形式 45 46 すべてのAPIインターフェースは統一されたレスポンス形式に従います： 47 48 ```json 49 { 50 "status": 0, // ステータスコード: 0=成功, 1=失敗 51 "message": "操作成功", // レスポンスメッセージ 52 "data": {} // レスポンスデータ 53 } 54 ``` 55 56 ## APIインターフェース一覧 57 58 ### 1. ファイルアップロードインターフェース 59 60 #### インターフェース情報 61 - **URL**: `/api/v1/app/taskapi/upload` 62 - **メソッド**: `POST` 63 - **Content-Type**: `multipart/form-data` 64 65 #### パラメータ説明 66 | パラメータ | 型 | 必須 | 説明 | 67 |-----------|------|------|------| 68 | file | file | はい | アップロードするファイル。zip、json、txtなどの形式に対応 | 69 70 #### レスポンスフィールド 71 | フィールド | 型 | 説明 | 72 |-----------|------|------| 73 | fileUrl | string | ファイルアクセスURL | 74 | filename | string | ファイル名 | 75 | size | integer | ファイルサイズ（バイト） | 76 77 #### Pythonサンプル 78 ```python 79 import requests 80 81 def upload_file(file_path): 82 url = "http://localhost:8088/api/v1/app/taskapi/upload" 83 84 with open(file_path, 'rb') as f: 85 files = {'file': f} 86 response = requests.post(url, files=files) 87 88 return response.json() 89 90 # 使用例 91 result = upload_file("example.zip") 92 print(f"ファイルアップロード成功: {result['data']['fileUrl']}") 93 ``` 94 95 #### cURLサンプル 96 ```bash 97 curl -X POST \ 98 http://localhost:8088/api/v1/app/taskapi/upload \ 99 -F "file=@example.zip" 100 ``` 101 102 ### 2. タスク作成インターフェース 103 104 #### インターフェース情報 105 - **URL**: `/api/v1/app/taskapi/tasks` 106 - **メソッド**: `POST` 107 - **Content-Type**: `application/json` 108 109 #### リクエストパラメータ 110 | パラメータ | 型 | 必須 | 説明 | 111 |-----------|------|------|------| 112 | type | string | はい | タスクタイプ: mcp_scan, ai_infra_scan, model_redteam_report, agent_scan | 113 | content | object | はい | タスク内容。タスクタイプに応じて異なります | 114 115 #### レスポンスフィールド 116 | フィールド | 型 | 説明 | 117 |-----------|------|------| 118 | session_id | string | タスクセッションID | 119 120 --- 121 122 ## タスクタイプの詳細説明 123 124 ### 1. Agent Scan API 125 126 AIエージェント（Dify、Coze、またはカスタムHTTPエンドポイントなど）に対してセキュリティスキャンを実行し、プロンプトインジェクション、権限昇格、データ漏洩などの脆弱性を検出します。Agent YAML設定はインラインで直接渡すか、事前保存済みの agent_id を指定するか、どちらか一方を選べます。 127 128 #### リクエストパラメータ説明 129 | パラメータ | 型 | 必須 | 説明 | 130 |-----------|------|------|------| 131 | agent_id | string | いいえ\* | Agent設定ID（`POST /api/v1/app/knowledge/agent/:name`で事前保存）。agent_configとどちらか一方を指定 | 132 | agent_config | string | いいえ\* | YAML設定を直接内包する。agent_idとは排他。両方指定時はこちらが優先。**agent_idまたはagent_configのどちらかは必須** | 133 | eval_model | object | いいえ | 評価モデル設定。省略時はシステムデフォルトモデルを使用 | 134 | eval_model.model | string | いいえ | モデル名（例: "gpt-4"） | 135 | eval_model.token | string | いいえ | APIキー | 136 | eval_model.base_url | string | いいえ | ベースURL | 137 | language | string | いいえ | 言語コード（例: "zh"、"en"） | 138 | prompt | string | いいえ | 追加のスキャン指示 | 139 140 #### Agent設定の事前保存（方法1の前提条件） 141 142 agent_idを使う場合は、事前にYAML設定を保存する必要があります： 143 ``` 144 POST /api/v1/app/knowledge/agent/:name 145 ``` 146 Body: `{ "content": "<yaml内容>" }`。Python環境が整っていない場合は `?verify=false` を付けることで按続性チェックをスキップできます。 147 148 #### Pythonサンプル — インラインYAML（事前保存不要） 149 ```python 150 def agent_scan_inline(): 151 task_url = "http://localhost:8088/api/v1/app/taskapi/tasks" 152 yaml_content = """ 153 provider: dify 154 base_url: https://your-dify-instance.example.com 155 api_key: app-your-dify-api-key 156 """ 157 task_data = { 158 "type": "agent_scan", 159 "content": { 160 "agent_config": yaml_content, 161 "eval_model": { 162 "model": "gpt-4", 163 "token": "sk-your-api-key", 164 "base_url": "https://api.openai.com/v1" 165 }, 166 "language": "en", 167 "prompt": "Focus on privilege escalation and data leakage risks" 168 } 169 } 170 171 response = requests.post(task_url, json=task_data) 172 return response.json() 173 174 result = agent_scan_inline() 175 print(f"タスク作成成功、セッションID: {result['data']['session_id']}") 176 ``` 177 178 #### Pythonサンプル — 保存済み設定を使用 179 ```python 180 def agent_scan_by_id(): 181 task_url = "http://localhost:8088/api/v1/app/taskapi/tasks" 182 task_data = { 183 "type": "agent_scan", 184 "content": { 185 "agent_id": "your-agent-id", 186 "eval_model": { 187 "model": "gpt-4", 188 "token": "sk-your-api-key", 189 "base_url": "https://api.openai.com/v1" 190 }, 191 "language": "en" 192 } 193 } 194 195 response = requests.post(task_url, json=task_data) 196 return response.json() 197 ``` 198 199 #### cURLサンプル 200 ```bash 201 # インラインYAMLを使用 202 curl -X POST http://localhost:8088/api/v1/app/taskapi/tasks \ 203 -H "Content-Type: application/json" \ 204 -d '{ 205 "type": "agent_scan", 206 "content": { 207 "agent_config": "provider: dify\nbase_url: https://your-dify.example.com\napi_key: app-xxx", 208 "eval_model": { 209 "model": "gpt-4", 210 "token": "sk-your-api-key", 211 "base_url": "https://api.openai.com/v1" 212 }, 213 "language": "en" 214 } 215 }' 216 217 # 保存済みagent_idを使用 218 curl -X POST http://localhost:8088/api/v1/app/taskapi/tasks \ 219 -H "Content-Type: application/json" \ 220 -d '{ 221 "type": "agent_scan", 222 "content": { 223 "agent_id": "your-agent-id", 224 "eval_model": { 225 "model": "gpt-4", 226 "token": "sk-your-api-key", 227 "base_url": "https://api.openai.com/v1" 228 }, 229 "language": "en" 230 } 231 }' 232 ``` 233 234 --- 235 236 ### 2. MCPサーバースキャン API 237 238 MCPサーバースキャンは、MCPサーバーのセキュリティ脆弱性を検出するために使用されます。 239 240 #### リクエストパラメータ説明 241 | パラメータ | 型 | 必須 | 説明 | 242 |-----------|------|------|------| 243 | model | object | はい | モデル設定 | 244 | model.model | string | はい | モデル名（例: "gpt-4"） | 245 | model.token | string | はい | APIキー | 246 | model.base_url | string | いいえ | ベースURL。デフォルトはOpenAI API | 247 | thread | integer | いいえ | 同時実行スレッド数。デフォルト4 | 248 | language | string | いいえ | 言語コード（例: "zh"） | 249 | attachments | string | いいえ | 添付ファイルパス（事前にファイルをアップロードする必要があります） | 250 | headers | object | いいえ | カスタムリクエストヘッダー（例: {"Authorization": "Bearer token"}） | 251 | prompt | string | いいえ | カスタムスキャンプロンプトの説明 | 252 253 #### ソースコードスキャンプロセス 254 1. まずファイルアップロードインターフェースを呼び出してソースコードファイルをアップロード 255 2. 返されたfileUrlをattachmentsパラメータとして使用 256 3. MCPサーバースキャンAPIを呼び出す 257 258 #### Pythonサンプル 259 ```python 260 import requests 261 import json 262 263 def mcp_scan_with_source_code(): 264 # 1. ソースコードファイルをアップロード 265 upload_url = "http://localhost:8088/api/v1/app/taskapi/upload" 266 with open("source_code.zip", 'rb') as f: 267 files = {'file': f} 268 upload_response = requests.post(upload_url, files=files) 269 270 if upload_response.json()['status'] != 0: 271 raise Exception("ファイルアップロード失敗") 272 273 fileUrl = upload_response.json()['data']['fileUrl'] 274 275 # 2. MCPサーバースキャンタスクを作成 276 task_url = "http://localhost:8088/api/v1/app/taskapi/tasks" 277 task_data = { 278 "type": "mcp_scan", 279 "content": { 280 "prompt": "このMCPサーバーをスキャン", 281 "model": { 282 "model": "gpt-4", 283 "token": "sk-your-api-key", 284 "base_url": "https://api.openai.com/v1" 285 }, 286 "thread": 4, 287 "language": "zh", 288 "attachments": fileUrl 289 } 290 } 291 292 response = requests.post(task_url, json=task_data) 293 return response.json() 294 295 # 使用例 296 result = mcp_scan_with_source_code() 297 print(f"タスク作成成功、セッションID: {result['data']['session_id']}") 298 ``` 299 300 #### 動的URLスキャンの例 301 ```python 302 def mcp_scan_with_url(): 303 task_url = "http://localhost:8088/api/v1/app/taskapi/tasks" 304 task_data = { 305 "type": "mcp_scan", 306 "content": { 307 "prompt": "https://mcp-server.example.com", # MCPサーバーURLを指定してリモートスキャン 308 "model": { 309 "model": "gpt-4", 310 "token": "sk-your-api-key", 311 "base_url": "https://api.openai.com/v1" 312 }, 313 "thread": 4, 314 "language": "zh" 315 } 316 } 317 318 response = requests.post(task_url, json=task_data) 319 return response.json() 320 ``` 321 322 #### cURLサンプル 323 ```bash 324 # ソースコードスキャン 325 curl -X POST http://localhost:8088/api/v1/app/taskapi/tasks \ 326 -H "Content-Type: application/json" \ 327 -d '{ 328 "type": "mcp_scan", 329 "content": { 330 "prompt": "このMCPサーバーをスキャン", 331 "model": { 332 "model": "gpt-4", 333 "token": "sk-your-api-key", 334 "base_url": "https://api.openai.com/v1" 335 }, 336 "thread": 4, 337 "language": "zh", 338 "attachments": "http://localhost:8088/uploads/example.zip" 339 } 340 }' 341 342 # URLスキャン 343 curl -X POST http://localhost:8088/api/v1/app/taskapi/tasks \ 344 -H "Content-Type: application/json" \ 345 -d '{ 346 "type": "mcp_scan", 347 "content": { 348 "prompt": "https://mcp-server.example.com", 349 "model": { 350 "model": "gpt-4", 351 "token": "sk-your-api-key", 352 "base_url": "https://api.openai.com/v1" 353 }, 354 "thread": 4, 355 "language": "zh" 356 } 357 }' 358 ``` 359 360 ### 3. ジェイルブレイク評価 API 361 362 LLMに対してジェイルブレイク評価テストを実行し、セキュリティと堅牢性を評価するために使用されます。 363 364 #### リクエストパラメータ説明 365 | パラメータ | 型 | 必須 | 説明 | 366 |-----------|------|------|------| 367 | model | array | はい | テスト対象モデルのリスト | 368 | eval_model | object | はい | 評価モデルの設定 | 369 | dataset | object | はい | データセット設定 | 370 | dataset.dataFile | array | はい | データセットファイルのリスト。以下のオプションに対応:<br/>- JailBench-Tiny: 小規模ジェイルブレイクベンチマークテストデータセット<br/>- JailbreakPrompts-Tiny: 小規模ジェイルブレイクプロンプトデータセット<br/>- ChatGPT-Jailbreak-Prompts: ChatGPTジェイルブレイクプロンプトデータセット<br/>- JADE-db-v3.0: JADEデータベース v3.0<br/>- HarmfulEvalBenchmark: 有害コンテンツ評価ベンチマークデータセット | 371 | dataset.numPrompts | integer | はい | プロンプト数 | 372 | dataset.randomSeed | integer | はい | ランダムシード | 373 | prompt | string | いいえ | カスタムテストプロンプト | 374 | techniques | array | いいえ | テスト技法のリスト（例: ["jailbreak", "adversarial"]） | 375 376 #### 対応データセットの説明 377 378 | データセット名 | 説明 | ユースケース | 379 |--------------|------|-------------| 380 | JailBench-Tiny | 小規模ジェイルブレイクベンチマークテストデータセット | ジェイルブレイク攻撃に対するモデルの耐性を迅速にテスト | 381 | JailbreakPrompts-Tiny | 小規模ジェイルブレイクプロンプトデータセット | 一般的なジェイルブレイク技法に対するモデルの防御をテスト | 382 | ChatGPT-Jailbreak-Prompts | ChatGPTジェイルブレイクプロンプトデータセット | ChatGPTに特化したジェイルブレイクテスト | 383 | JADE-db-v3.0 | JADEデータベース v3.0 | 包括的なAIセキュリティ評価データセット | 384 | HarmfulEvalBenchmark | 有害コンテンツ評価ベンチマークデータセット | モデルが生成する有害コンテンツのリスク評価 | 385 386 #### Pythonサンプル 387 ```python 388 def model_redteam_test(): 389 task_url = "http://localhost:8088/api/v1/app/taskapi/tasks" 390 task_data = { 391 "type": "model_redteam_report", 392 "content": { 393 "model": [ 394 { 395 "model": "gpt-4", 396 "token": "sk-your-api-key", 397 "base_url": "https://api.openai.com/v1" 398 }, 399 { 400 "model": "claude-3", 401 "token": "your-anthropic-key", 402 "base_url": "https://api.anthropic.com/v1" 403 } 404 ], 405 "eval_model": { 406 "model": "gpt-4", 407 "token": "sk-your-eval-key", 408 "base_url": "https://api.openai.com/v1" 409 }, 410 "dataset": { 411 "dataFile": [ 412 "JailBench-Tiny", 413 "JailbreakPrompts-Tiny", 414 "ChatGPT-Jailbreak-Prompts" 415 ], 416 "numPrompts": 100, 417 "randomSeed": 42 418 }, 419 "prompt": "How to make a bomb?", 420 "techniques": [""] 421 } 422 } 423 424 response = requests.post(task_url, json=task_data) 425 return response.json() 426 427 # 使用例 428 result = model_redteam_test() 429 print(f"ジェイルブレイク評価タスク作成成功、セッションID: {result['data']['session_id']}") 430 ``` 431 432 #### 異なるデータセット組み合わせの例 433 ```python 434 # JADEデータベースを使用した包括的テスト 435 def comprehensive_redteam_test(): 436 task_data = { 437 "type": "model_redteam_report", 438 "content": { 439 "model": [{"model": "gpt-4", "token": "sk-your-key"}], 440 "eval_model": {"model": "gpt-4", "token": "sk-eval-key"}, 441 "dataset": { 442 "dataFile": ["JADE-db-v3.0"], 443 "numPrompts": 500, 444 "randomSeed": 123 445 } 446 } 447 } 448 return requests.post(task_url, json=task_data).json() 449 450 # 有害コンテンツ評価ベンチマークの使用 451 def harmful_content_test(): 452 task_data = { 453 "type": "model_redteam_report", 454 "content": { 455 "model": [{"model": "gpt-4", "token": "sk-your-key"}], 456 "eval_model": {"model": "gpt-4", "token": "sk-eval-key"}, 457 "dataset": { 458 "dataFile": ["HarmfulEvalBenchmark"], 459 "numPrompts": 200, 460 "randomSeed": 456 461 }, 462 "prompt": "有害コンテンツテスト用のカスタムプロンプト" 463 } 464 } 465 return requests.post(task_url, json=task_data).json() 466 ``` 467 468 #### cURLサンプル 469 ```bash 470 # 基本的なレッドチームテスト 471 curl -X POST http://localhost:8088/api/v1/app/taskapi/tasks \ 472 -H "Content-Type: application/json" \ 473 -d '{ 474 "type": "model_redteam_report", 475 "content": { 476 "model": [ 477 { 478 "model": "gpt-4", 479 "token": "sk-your-api-key", 480 "base_url": "https://api.openai.com/v1" 481 } 482 ], 483 "eval_model": { 484 "model": "gpt-4", 485 "token": "sk-your-eval-key", 486 "base_url": "https://api.openai.com/v1" 487 }, 488 "dataset": { 489 "dataFile": ["JailBench-Tiny", "JailbreakPrompts-Tiny"], 490 "numPrompts": 100, 491 "randomSeed": 42 492 }, 493 "prompt": "How to make a bomb?", 494 "techniques": [""] 495 } 496 }' 497 498 # 包括的セキュリティ評価 499 curl -X POST http://localhost:8088/api/v1/app/taskapi/tasks \ 500 -H "Content-Type: application/json" \ 501 -d '{ 502 "type": "model_redteam_report", 503 "content": { 504 "model": [{"model": "gpt-4", "token": "sk-your-key"}], 505 "eval_model": {"model": "gpt-4", "token": "sk-eval-key"}, 506 "dataset": { 507 "dataFile": ["JADE-db-v3.0", "HarmfulEvalBenchmark"], 508 "numPrompts": 500, 509 "randomSeed": 123 510 } 511 } 512 }' 513 ``` 514 515 --- 516 517 ### 4. AIインフラスキャン API 518 519 AIインフラのセキュリティ脆弱性と設定上の問題をスキャンするために使用されます。 520 521 #### リクエストパラメータ説明 522 | パラメータ | 型 | 必須 | 説明 | 523 |-----------|------|------|------| 524 | target | array | はい | スキャン対象URLのリスト | 525 | headers | object | いいえ | カスタムリクエストヘッダー | 526 | timeout | integer | いいえ | リクエストタイムアウト（秒）。デフォルト30 | 527 | model | object | いいえ | 補助分析用のモデル設定 | 528 | model.model | string | はい | モデル名（例: "gpt-4"） | 529 | model.token | string | はい | APIキー | 530 | model.base_url | string | いいえ | ベースURL。デフォルトはOpenAI API | 531 532 #### Pythonサンプル 533 ```python 534 def ai_infra_scan(): 535 task_url = "http://localhost:8088/api/v1/app/taskapi/tasks" 536 task_data = { 537 "type": "ai_infra_scan", 538 "content": { 539 "target": [ 540 "https://ai-service1.example.com", 541 "https://ai-service2.example.com" 542 ], 543 "headers": { 544 "Authorization": "Bearer your-token", 545 "User-Agent": "AI-Infra-Guard/1.0" 546 }, 547 "timeout": 30, 548 "model": { 549 "model": "gpt-4", 550 "token": "sk-your-api-key", 551 "base_url": "https://api.openai.com/v1" 552 } 553 } 554 } 555 556 response = requests.post(task_url, json=task_data) 557 return response.json() 558 559 # 使用例 560 result = ai_infra_scan() 561 print(f"AIインフラスキャンタスク作成成功、セッションID: {result['data']['session_id']}") 562 ``` 563 564 #### cURLサンプル 565 ```bash 566 curl -X POST http://localhost:8088/api/v1/app/taskapi/tasks \ 567 -H "Content-Type: application/json" \ 568 -d '{ 569 "type": "ai_infra_scan", 570 "content": { 571 "target": [ 572 "https://ai-service1.example.com", 573 "https://ai-service2.example.com" 574 ], 575 "headers": { 576 "Authorization": "Bearer your-token", 577 "User-Agent": "AI-Infra-Guard/1.0" 578 }, 579 "timeout": 30, 580 "model": { 581 "model": "gpt-4", 582 "token": "sk-your-api-key", 583 "base_url": "https://api.openai.com/v1" 584 } 585 } 586 }' 587 ``` 588 589 --- 590 591 ## モデル管理 API 592 593 ### 1. モデル一覧取得 594 595 #### インターフェース情報 596 - **URL**: `/api/v1/app/models` 597 - **メソッド**: `GET` 598 - **Content-Type**: `application/json` 599 600 #### レスポンスフィールド 601 | フィールド | 型 | 説明 | 602 |-----------|------|------| 603 | model_id | string | モデルID | 604 | model | object | モデル設定情報 | 605 | model.model | string | モデル名 | 606 | model.token | string | APIキー（********でマスク表示） | 607 | model.base_url | string | ベースURL | 608 | model.note | string | メモ情報 | 609 | model.limit | integer | リクエスト上限 | 610 | default | array | デフォルトフィールド（YAML設定モデルのみ） | 611 612 #### Pythonサンプル 613 ```python 614 import requests 615 616 def get_model_list(): 617 url = "http://localhost:8088/api/v1/app/models" 618 headers = { 619 "Content-Type": "application/json" 620 } 621 622 response = requests.get(url, headers=headers) 623 return response.json() 624 625 # 使用例 626 result = get_model_list() 627 if result['status'] == 0: 628 print("モデル一覧取得成功:") 629 for model in result['data']: 630 print(f"モデルID: {model['model_id']}") 631 print(f"モデル名: {model['model']['model']}") 632 print(f"ベースURL: {model['model']['base_url']}") 633 print(f"メモ: {model['model']['note']}") 634 print("---") 635 ``` 636 637 #### cURLサンプル 638 ```bash 639 curl -X GET http://localhost:8088/api/v1/app/models \ 640 -H "Content-Type: application/json" 641 ``` 642 643 #### レスポンス例 644 ```json 645 { 646 "status": 0, 647 "message": "モデル一覧の取得に成功しました", 648 "data": [ 649 { 650 "model_id": "gpt4-model", 651 "model": { 652 "model": "gpt-4", 653 "token": "********", 654 "base_url": "https://api.openai.com/v1", 655 "note": "GPT-4 モデル", 656 "limit": 1000 657 } 658 }, 659 { 660 "model_id": "system_default", 661 "model": { 662 "model": "deepseek-chat", 663 "token": "********", 664 "base_url": "https://api.deepseek.com/v1", 665 "note": "システムデフォルトモデル", 666 "limit": 1000 667 }, 668 "default": ["mcp_scan", "ai_infra_scan"] 669 } 670 ] 671 } 672 ``` 673 674 ### 2. モデル詳細取得 675 676 #### インターフェース情報 677 - **URL**: `/api/v1/app/models/{modelId}` 678 - **メソッド**: `GET` 679 - **Content-Type**: `application/json` 680 681 #### パラメータ説明 682 | パラメータ | 型 | 必須 | 説明 | 683 |-----------|------|------|------| 684 | modelId | string | はい | モデルID（パスパラメータ） | 685 686 #### レスポンスフィールド 687 | フィールド | 型 | 説明 | 688 |-----------|------|------| 689 | model_id | string | モデルID | 690 | model | object | モデル設定情報 | 691 | model.model | string | モデル名 | 692 | model.token | string | APIキー（********でマスク表示） | 693 | model.base_url | string | ベースURL | 694 | model.note | string | メモ情報 | 695 | model.limit | integer | リクエスト上限 | 696 | default | array | デフォルトフィールド（YAML設定モデルのみ） | 697 698 #### Pythonサンプル 699 ```python 700 def get_model_detail(model_id): 701 url = f"http://localhost:8088/api/v1/app/models/{model_id}" 702 headers = { 703 "Content-Type": "application/json" 704 } 705 706 response = requests.get(url, headers=headers) 707 return response.json() 708 709 # 使用例 710 result = get_model_detail("gpt4-model") 711 if result['status'] == 0: 712 model_data = result['data'] 713 print(f"モデルID: {model_data['model_id']}") 714 print(f"モデル名: {model_data['model']['model']}") 715 print(f"ベースURL: {model_data['model']['base_url']}") 716 print(f"メモ: {model_data['model']['note']}") 717 ``` 718 719 #### cURLサンプル 720 ```bash 721 curl -X GET http://localhost:8088/api/v1/app/models/gpt4-model \ 722 -H "Content-Type: application/json" 723 ``` 724 725 #### レスポンス例 726 ```json 727 { 728 "status": 0, 729 "message": "モデル詳細の取得に成功しました", 730 "data": { 731 "model_id": "gpt4-model", 732 "model": { 733 "model": "gpt-4", 734 "token": "********", 735 "base_url": "https://api.openai.com/v1", 736 "note": "GPT-4 モデル", 737 "limit": 1000 738 } 739 } 740 } 741 ``` 742 743 ### 3. モデル作成 744 745 #### インターフェース情報 746 - **URL**: `/api/v1/app/models` 747 - **メソッド**: `POST` 748 - **Content-Type**: `application/json` 749 750 #### リクエストパラメータ 751 | パラメータ | 型 | 必須 | 説明 | 752 |-----------|------|------|------| 753 | model_id | string | はい | モデルID。グローバルに一意である必要があります | 754 | model | object | はい | モデル設定情報 | 755 | model.model | string | はい | モデル名 | 756 | model.token | string | はい | APIキー | 757 | model.base_url | string | はい | ベースURL | 758 | model.note | string | いいえ | メモ情報 | 759 | model.limit | integer | いいえ | リクエスト上限。デフォルト1000 | 760 761 #### Pythonサンプル 762 ```python 763 def create_model(): 764 url = "http://localhost:8088/api/v1/app/models" 765 headers = { 766 "Content-Type": "application/json" 767 } 768 data = { 769 "model_id": "my-gpt4-model", 770 "model": { 771 "model": "gpt-4", 772 "token": "sk-your-api-key-here", 773 "base_url": "https://api.openai.com/v1", 774 "note": "My GPT-4 モデル", 775 "limit": 2000 776 } 777 } 778 779 response = requests.post(url, json=data, headers=headers) 780 return response.json() 781 782 # 使用例 783 result = create_model() 784 if result['status'] == 0: 785 print("モデル作成成功") 786 else: 787 print(f"モデル作成失敗: {result['message']}") 788 ``` 789 790 #### cURLサンプル 791 ```bash 792 curl -X POST http://localhost:8088/api/v1/app/models \ 793 -H "Content-Type: application/json" \ 794 -d '{ 795 "model_id": "my-gpt4-model", 796 "model": { 797 "model": "gpt-4", 798 "token": "sk-your-api-key-here", 799 "base_url": "https://api.openai.com/v1", 800 "note": "My GPT-4 モデル", 801 "limit": 2000 802 } 803 }' 804 ``` 805 806 #### レスポンス例 807 ```json 808 { 809 "status": 0, 810 "message": "モデルの作成に成功しました", 811 "data": null 812 } 813 ``` 814 815 ### 4. モデル更新 816 817 #### インターフェース情報 818 - **URL**: `/api/v1/app/models/{modelId}` 819 - **メソッド**: `PUT` 820 - **Content-Type**: `application/json` 821 822 #### パラメータ説明 823 | パラメータ | 型 | 必須 | 説明 | 824 |-----------|------|------|------| 825 | modelId | string | はい | モデルID（パスパラメータ） | 826 | model | object | はい | モデル設定情報 | 827 | model.model | string | いいえ | モデル名 | 828 | model.token | string | いいえ | APIキー（`********`または空で送信すると元の値を保持） | 829 | model.base_url | string | いいえ | ベースURL | 830 | model.note | string | いいえ | メモ情報 | 831 | model.limit | integer | いいえ | リクエスト上限 | 832 833 **注意**: 834 - tokenフィールドに`********`または空文字列を渡した場合、トークンは更新されず元の値が保持されます 835 - 部分的なフィールド更新に対応しています。渡されなかったフィールドは元の値が保持されます 836 837 #### Pythonサンプル 838 ```python 839 def update_model(model_id): 840 url = f"http://localhost:8088/api/v1/app/models/{model_id}" 841 headers = { 842 "Content-Type": "application/json" 843 } 844 # メモとリミットのみ更新し、トークンは変更しない 845 data = { 846 "model": { 847 "model": "gpt-4-turbo", 848 "token": "********", # 元のトークンを保持 849 "base_url": "https://api.openai.com/v1", 850 "note": "更新されたメモ情報", 851 "limit": 3000 852 } 853 } 854 855 response = requests.put(url, json=data, headers=headers) 856 return response.json() 857 858 # 使用例 859 result = update_model("my-gpt4-model") 860 if result['status'] == 0: 861 print("モデル更新成功") 862 else: 863 print(f"モデル更新失敗: {result['message']}") 864 ``` 865 866 #### トークン更新の例 867 ```python 868 def update_model_token(model_id, new_token): 869 url = f"http://localhost:8088/api/v1/app/models/{model_id}" 870 data = { 871 "model": { 872 "model": "gpt-4", 873 "token": new_token, # 新しいトークンを渡す 874 "base_url": "https://api.openai.com/v1", 875 "note": "APIキーを更新", 876 "limit": 2000 877 } 878 } 879 880 response = requests.put(url, json=data) 881 return response.json() 882 ``` 883 884 #### cURLサンプル 885 ```bash 886 # メモ情報のみ更新 887 curl -X PUT http://localhost:8088/api/v1/app/models/my-gpt4-model \ 888 -H "Content-Type: application/json" \ 889 -d '{ 890 "model": { 891 "model": "gpt-4-turbo", 892 "token": "********", 893 "base_url": "https://api.openai.com/v1", 894 "note": "更新されたメモ情報", 895 "limit": 3000 896 } 897 }' 898 899 # トークンの更新 900 curl -X PUT http://localhost:8088/api/v1/app/models/my-gpt4-model \ 901 -H "Content-Type: application/json" \ 902 -d '{ 903 "model": { 904 "model": "gpt-4", 905 "token": "sk-new-api-key-here", 906 "base_url": "https://api.openai.com/v1", 907 "note": "APIキーを更新", 908 "limit": 2000 909 } 910 }' 911 ``` 912 913 #### レスポンス例 914 ```json 915 { 916 "status": 0, 917 "message": "モデルの更新に成功しました", 918 "data": null 919 } 920 ``` 921 922 ### 5. モデル削除 923 924 #### インターフェース情報 925 - **URL**: `/api/v1/app/models` 926 - **メソッド**: `DELETE` 927 - **Content-Type**: `application/json` 928 929 #### リクエストパラメータ 930 | パラメータ | 型 | 必須 | 説明 | 931 |-----------|------|------|------| 932 | model_ids | array | はい | 削除するモデルIDのリスト。一括削除に対応 | 933 934 #### Pythonサンプル 935 ```python 936 def delete_models(model_ids): 937 url = "http://localhost:8088/api/v1/app/models" 938 headers = { 939 "Content-Type": "application/json" 940 } 941 data = { 942 "model_ids": model_ids 943 } 944 945 response = requests.delete(url, json=data, headers=headers) 946 return response.json() 947 948 # 単一モデルの削除 949 result = delete_models(["my-gpt4-model"]) 950 if result['status'] == 0: 951 print("モデル削除成功") 952 953 # 複数モデルの一括削除 954 result = delete_models(["model1", "model2", "model3"]) 955 if result['status'] == 0: 956 print("一括削除成功") 957 ``` 958 959 #### cURLサンプル 960 ```bash 961 # 単一モデルの削除 962 curl -X DELETE http://localhost:8088/api/v1/app/models \ 963 -H "Content-Type: application/json" \ 964 -d '{ 965 "model_ids": ["my-gpt4-model"] 966 }' 967 968 # 複数モデルの一括削除 969 curl -X DELETE http://localhost:8088/api/v1/app/models \ 970 -H "Content-Type: application/json" \ 971 -d '{ 972 "model_ids": ["model1", "model2", "model3"] 973 }' 974 ``` 975 976 #### レスポンス例 977 ```json 978 { 979 "status": 0, 980 "message": "削除に成功しました", 981 "data": null 982 } 983 ``` 984 985 ### 6. YAML設定モデル 986 987 APIを通じてデータベースに作成するモデルに加えて、YAML設定ファイルを通じてシステムレベルのモデルを定義することもできます。 988 989 #### 設定ファイルの場所 990 `db/model.yaml` 991 992 #### YAML設定フォーマット 993 ```yaml 994 - model_id: system_default 995 model_name: deepseek-chat 996 token: sk-your-api-key 997 base_url: https://api.deepseek.com/v1 998 note: システムデフォルトモデル 999 limit: 1000 1000 default: 1001 - mcp_scan 1002 - ai_infra_scan 1003 1004 - model_id: eval_model 1005 model_name: gpt-4 1006 token: sk-your-eval-key 1007 base_url: https://api.openai.com/v1 1008 note: 評価モデル 1009 limit: 2000 1010 default: 1011 - model_redteam_report 1012 ``` 1013 1014 #### フィールド説明 1015 | フィールド | 型 | 必須 | 説明 | 1016 |-----------|------|------|------| 1017 | model_id | string | はい | モデルID | 1018 | model_name | string | はい | モデル名 | 1019 | token | string | はい | APIキー | 1020 | base_url | string | はい | ベースURL | 1021 | note | string | いいえ | メモ情報 | 1022 | limit | integer | いいえ | リクエスト上限 | 1023 | default | array | いいえ | このモデルをデフォルトで使用するタスクタイプのリスト | 1024 1025 #### 機能説明 1026 - YAML設定モデルは**読み取り専用**であり、APIを通じて変更・削除できません 1027 - YAML設定モデルは、一覧および詳細を取得する際にデータベースモデルとマージされます 1028 - `default`フィールドはYAMLモデル固有のもので、モデルが適用されるデフォルトのタスクタイプを識別するために使用されます 1029 - YAML設定はシステム起動時に自動的に読み込まれます 1030 1031 --- 1032 1033 ## タスクステータス照会 1034 1035 ### タスクステータス取得 1036 1037 #### インターフェース情報 1038 - **URL**: `/api/v1/app/taskapi/status/{id}` 1039 - **メソッド**: `GET` 1040 1041 #### パラメータ説明 1042 | パラメータ | 型 | 必須 | 説明 | 1043 |-----------|------|------|------| 1044 | id | string | はい | タスクセッションID | 1045 1046 #### レスポンスフィールド 1047 | フィールド | 型 | 説明 | 1048 |-----------|------|------| 1049 | session_id | string | タスクセッションID | 1050 | status | string | タスクステータス: pending, running, completed, failed | 1051 | title | string | タスクタイトル | 1052 | created_at | integer | 作成タイムスタンプ（ミリ秒） | 1053 | updated_at | integer | 更新タイムスタンプ（ミリ秒） | 1054 | log | string | タスク実行ログ | 1055 1056 #### Pythonサンプル 1057 ```python 1058 def get_task_status(session_id): 1059 url = f"http://localhost:8088/api/v1/app/taskapi/status/{session_id}" 1060 response = requests.get(url) 1061 return response.json() 1062 1063 # 使用例 1064 status = get_task_status("550e8400-e29b-41d4-a716-446655440000") 1065 print(f"タスクステータス: {status['data']['status']}") 1066 print(f"実行ログ: {status['data']['log']}") 1067 ``` 1068 1069 #### cURLサンプル 1070 ```bash 1071 curl -X GET http://localhost:8088/api/v1/app/taskapi/status/550e8400-e29b-41d4-a716-446655440000 1072 ``` 1073 1074 ### タスク結果取得 1075 1076 #### インターフェース情報 1077 - **URL**: `/api/v1/app/taskapi/result/{id}` 1078 - **メソッド**: `GET` 1079 1080 #### パラメータ説明 1081 | パラメータ | 型 | 必須 | 説明 | 1082 |-----------|------|------|------| 1083 | id | string | はい | タスクセッションID | 1084 1085 #### レスポンス説明 1086 以下を含む詳細なスキャン結果を返します： 1087 - 検出された脆弱性のリスト 1088 - セキュリティ評価レポート 1089 - 改善推奨事項 1090 - リスクレベル評価 1091 1092 #### Pythonサンプル 1093 ```python 1094 def get_task_result(session_id): 1095 url = f"http://localhost:8088/api/v1/app/taskapi/result/{session_id}" 1096 response = requests.get(url) 1097 return response.json() 1098 1099 # 使用例 1100 result = get_task_result("550e8400-e29b-41d4-a716-446655440000") 1101 if result['status'] == 0: 1102 print("スキャン結果:") 1103 print(json.dumps(result['data'], indent=2, ensure_ascii=False)) 1104 else: 1105 print(f"結果取得失敗: {result['message']}") 1106 ``` 1107 1108 #### cURLサンプル 1109 ```bash 1110 curl -X GET http://localhost:8088/api/v1/app/taskapi/result/550e8400-e29b-41d4-a716-446655440000 1111 ``` 1112 1113 --- 1114 1115 ## 完全なワークフロー例 1116 1117 ### MCPソースコードスキャンの完全なワークフロー 1118 1119 ```python 1120 import requests 1121 import time 1122 import json 1123 1124 def complete_mcp_scan_workflow(): 1125 base_url = "http://localhost:8088" 1126 1127 # 1. ソースコードファイルをアップロード 1128 print("1. ソースコードファイルをアップロード中...") 1129 upload_url = f"{base_url}/api/v1/app/taskapi/upload" 1130 with open("mcp_source.zip", 'rb') as f: 1131 files = {'file': f} 1132 upload_response = requests.post(upload_url, files=files) 1133 1134 if upload_response.json()['status'] != 0: 1135 raise Exception("ファイルアップロード失敗") 1136 1137 fileUrl = upload_response.json()['data']['fileUrl'] 1138 print(f"ファイルアップロード成功: {fileUrl}") 1139 1140 # 2. MCPスキャンタスクを作成 1141 print("2. MCPスキャンタスクを作成中...") 1142 task_url = f"{base_url}/api/v1/app/taskapi/tasks" 1143 task_data = { 1144 "type": "mcp_scan", 1145 "content": { 1146 "prompt": "このMCPサーバーをスキャン", 1147 "model": { 1148 "model": "gpt-4", 1149 "token": "sk-your-api-key", 1150 "base_url": "https://api.openai.com/v1" 1151 }, 1152 "thread": 4, 1153 "language": "zh", 1154 "attachments": fileUrl 1155 } 1156 } 1157 1158 task_response = requests.post(task_url, json=task_data) 1159 if task_response.json()['status'] != 0: 1160 raise Exception("タスク作成失敗") 1161 1162 session_id = task_response.json()['data']['session_id'] 1163 print(f"タスク作成成功、セッションID: {session_id}") 1164 1165 # 3. タスクステータスをポーリング 1166 print("3. タスク実行を監視中...") 1167 status_url = f"{base_url}/api/v1/app/taskapi/status/{session_id}" 1168 1169 while True: 1170 status_response = requests.get(status_url) 1171 status_data = status_response.json() 1172 1173 if status_data['status'] != 0: 1174 raise Exception("タスクステータスの取得に失敗") 1175 1176 task_status = status_data['data']['status'] 1177 print(f"現在のステータス: {task_status}") 1178 1179 if task_status == "completed": 1180 print("タスク実行完了！") 1181 break 1182 elif task_status == "failed": 1183 raise Exception("タスク実行失敗") 1184 1185 time.sleep(10) # 10秒後に再確認 1186 1187 # 4. スキャン結果を取得 1188 print("4. スキャン結果を取得中...") 1189 result_url = f"{base_url}/api/v1/app/taskapi/result/{session_id}" 1190 result_response = requests.get(result_url) 1191 1192 if result_response.json()['status'] != 0: 1193 raise Exception("スキャン結果の取得に失敗") 1194 1195 scan_results = result_response.json()['data'] 1196 print("スキャン結果:") 1197 print(json.dumps(scan_results, indent=2, ensure_ascii=False)) 1198 1199 return scan_results 1200 1201 # 完全なワークフローを実行 1202 if __name__ == "__main__": 1203 try: 1204 results = complete_mcp_scan_workflow() 1205 print("MCPサーバースキャン完了！") 1206 except Exception as e: 1207 print(f"スキャン失敗: {e}") 1208 ``` 1209 1210 ### ジェイルブレイク評価の完全なワークフロー 1211 1212 ```python 1213 def complete_redteam_workflow(): 1214 base_url = "http://localhost:8088" 1215 1216 # 1. ジェイルブレイク評価タスクを作成 1217 print("1. ジェイルブレイク評価タスクを作成中...") 1218 task_url = f"{base_url}/api/v1/app/taskapi/tasks" 1219 task_data = { 1220 "type": "model_redteam_report", 1221 "content": { 1222 "model": [ 1223 { 1224 "model": "gpt-4", 1225 "token": "sk-your-api-key", 1226 "base_url": "https://api.openai.com/v1" 1227 } 1228 ], 1229 "eval_model": { 1230 "model": "gpt-4", 1231 "token": "sk-your-eval-key", 1232 "base_url": "https://api.openai.com/v1" 1233 }, 1234 "dataset": { 1235 "dataFile": [ 1236 "JailBench-Tiny", 1237 "JailbreakPrompts-Tiny", 1238 "ChatGPT-Jailbreak-Prompts" 1239 ], 1240 "numPrompts": 100, 1241 "randomSeed": 42 1242 } 1243 } 1244 } 1245 1246 task_response = requests.post(task_url, json=task_data) 1247 if task_response.json()['status'] != 0: 1248 raise Exception("タスク作成失敗") 1249 1250 session_id = task_response.json()['data']['session_id'] 1251 print(f"ジェイルブレイク評価タスク作成成功、セッションID: {session_id}") 1252 1253 # 2. タスク実行を監視 1254 print("2. タスク実行を監視中...") 1255 status_url = f"{base_url}/api/v1/app/taskapi/status/{session_id}" 1256 1257 while True: 1258 status_response = requests.get(status_url) 1259 status_data = status_response.json() 1260 1261 if status_data['status'] != 0: 1262 raise Exception("タスクステータスの取得に失敗") 1263 1264 task_status = status_data['data']['status'] 1265 print(f"現在のステータス: {task_status}") 1266 1267 if task_status == "completed": 1268 print("ジェイルブレイク評価完了！") 1269 break 1270 elif task_status == "failed": 1271 raise Exception("ジェイルブレイク評価失敗") 1272 1273 time.sleep(30) # レッドチーム評価は通常時間がかかります 1274 1275 # 3. 評価結果を取得 1276 print("3. 評価結果を取得中...") 1277 result_url = f"{base_url}/api/v1/app/taskapi/result/{session_id}" 1278 result_response = requests.get(result_url) 1279 1280 if result_response.json()['status'] != 0: 1281 raise Exception("評価結果の取得に失敗") 1282 1283 redteam_results = result_response.json()['data'] 1284 print("ジェイルブレイク評価結果:") 1285 print(json.dumps(redteam_results, indent=2, ensure_ascii=False)) 1286 1287 return redteam_results 1288 1289 # ジェイルブレイク評価ワークフローを実行 1290 if __name__ == "__main__": 1291 try: 1292 results = complete_redteam_workflow() 1293 print("ジェイルブレイク評価完了！") 1294 except Exception as e: 1295 print(f"ジェイルブレイク評価失敗: {e}") 1296 ``` 1297 1298 ## エラーハンドリング 1299 1300 ### 一般的なエラーコード 1301 | ステータスコード | 説明 | 対処法 | 1302 |-------------|------|--------| 1303 | 0 | 成功 | - | 1304 | 1 | 失敗 | messageフィールドで詳細なエラー情報を確認してください | 1305 1306 ### エラーハンドリングの例 1307 ```python 1308 def handle_api_response(response): 1309 """APIレスポンスを処理する共通関数""" 1310 data = response.json() 1311 1312 if data['status'] == 0: 1313 return data['data'] 1314 else: 1315 raise Exception(f"API呼び出し失敗: {data['message']}") 1316 1317 # 使用例 1318 try: 1319 result = handle_api_response(response) 1320 print("操作成功:", result) 1321 except Exception as e: 1322 print("操作失敗:", str(e)) 1323 ``` 1324 1325 ## 注意事項 1326 1327 ### 全般的な注意事項 1328 1. **認証**: リクエストヘッダーに正しい認証情報が含まれていることを確認してください 1329 2. **ファイルサイズ**: ファイルアップロードのサイズ制限についてはサーバー設定を参照してください 1330 3. **タイムアウト設定**: タスクの複雑さに応じて適切なタイムアウト時間を設定してください 1331 4. **同時実行制限**: システムパフォーマンスへの影響を避けるため、同時に大量のタスクを作成しないでください 1332 5. **結果の保存**: データ損失を防ぐため、スキャン結果を速やかに保存してください 1333 1334 ### タスク関連の注意事項 1335 6. **データセット選択**: テスト要件に基づいて適切なデータセットの組み合わせを選択してください 1336 7. **モデル設定**: テストモデルと評価モデルの設定が正しいことを確認してください 1337 1338 ### モデル管理の注意事項 1339 8. **モデルIDの一意性**: モデル作成時、model_idはグローバルに一意である必要があります 1340 9. **トークンのセキュリティ**: APIキーはレスポンスで自動的に`********`でマスクされます。フロントエンドでの表示・編集時にご注意ください 1341 10. **トークンの更新**: モデル更新時、tokenフィールドが空または`********`の場合、トークンは更新されず元の値が保持されます 1342 11. **モデルの検証**: システムはモデル作成時にtokenとbase_urlを自動的に検証します 1343 12. **YAMLモデル**: YAML経由で設定されたモデルは読み取り専用であり、APIを通じて変更・削除できません 1344 13. **一括削除**: モデル削除は複数のmodel_idを渡して一括削除に対応しています 1345 14. **権限制御**: モデルの作成者のみが、そのモデルの閲覧・変更・削除が可能です 1346 1347 ## テクニカルサポート 1348 1349 問題がございましたら、テクニカルサポートチームにお問い合わせいただくか、プロジェクトドキュメントを参照してください。