OpenAPI 3.0/3.1 spec 검증·보안감사·버전비교·예시생성·완성도 측정 — 30+ 규칙, 외부 의존성 0, 한국어 1급 / OpenAPI linter with 30+ rules, zero deps, Korean-first
호환 플랫폼: any
검사 결과: ["메타데이터 경고: 권장 필드 없음: 'requirements' (SKILL.md v2 권장)", "메타데이터 경고: 권장 필드 없음: 'changelog' (SKILL.md v2 권장)"]
✅ 보안 위험 항목이 발견되지 않았습니다.
AI 검수 단계
스킬 메타데이터에 따르면, 이 스킬은 네트워크, 파일 시스템, 서브프로세스 접근 권한이 없다고 명시되어 있습니다. 제공된 코드(`main.py`, `lib/*.py`)를 분석한 결과, `requests`, `socket`, `os.system`, `subprocess.run`, `open()` 등 외부 통신이나 파일 시스템 접근, 서브프로세스 실행을 시도하는 코드가 전혀 발견되지 않았습니다. 모든 작업은 표준 입력을 통해 OpenAPI 스펙(JSON 객체)을 받아 메모리 내에서 처리하고, 결과를 표준 출력으로 반환하는 방식으로 이루어집니다. 입력 크기 제한(5MB)도 설정되어 있어 잠재적인 리소스 고갈 공격에 대한 방어책도 마련되어 있습니다. 정적 분석 결과에서도 어떠한 위험 요소나 난독화, 금지된 실행 파일이 발견되지 않아 코드의 안전성이 추가로 확인되었습니다. 따라서 선언된 권한과 실제 코드가 일치하며, 악의적인 목적의 코드나 무단 데이터 수집/전송 행위가 없어 안전하다고 판단됩니다.
이 스킬의 대표적인 입출력 예시입니다. 에이전트는 이 예시를 보고 스킬 호출 방법과 결과 형태를 이해할 수 있습니다.
깨끗한 spec 을 lint — finding 없음 / Lint a well-formed spec with no issues
{
"action": "lint",
"spec": {
"components": {
"schemas": {
"User": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"type": "object"
}
},
"securitySchemes": {
"BearerAuth": {
"bearerFormat": "JWT",
"scheme": "bearer",
"type": "http"
}
}
},
"info": {
"contact": {
"email": "api@example.com"
},
"description": "\uc0d8\ud50c API",
"license": {
"name": "MIT"
},
"title": "Sample API",
"version": "1.0.0"
},
"openapi": "3.0.3",
"paths": {
"/users": {
"get": {
"description": "\uc0ac\uc6a9\uc790 \ubaa9\ub85d\uc744 \ud398\uc774\uc9c0\ub124\uc774\uc158\uc73c\ub85c \ubc18\ud658\ud569\ub2c8\ub2e4",
"operationId": "listUsers",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"default": 20,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": [
{
"id": 1,
"name": "\ud64d\uae38\ub3d9"
}
],
"schema": {
"items": {
"$ref": "#/components/schemas/User"
},
"type": "array"
}
}
},
"description": "\uc131\uacf5"
},
"400": {
"description": "\uc798\ubabb\ub41c \uc694\uccad"
},
"401": {
"description": "\uc778\uc99d \ud544\uc694"
}
},
"security": [
{
"BearerAuth": []
}
],
"summary": "\uc0ac\uc6a9\uc790 \ubaa9\ub85d",
"tags": [
"users"
]
}
}
},
"servers": [
{
"url": "https://api.example.com/v1"
}
],
"tags": [
{
"description": "\uc0ac\uc6a9\uc790 \uad00\ub828",
"name": "users"
}
]
}
}
{
"action": "lint",
"by_category": {
"DOC": 2
},
"by_severity": {
"error": 0,
"info": 2,
"warning": 0
},
"finding_count": 2,
"findings": [
{
"category": "DOC",
"fix_hint": {
"example": "\"externalDocs\": {\"url\": \"https://docs.example.com\"}",
"how": "url + description \ud3ec\ud568 externalDocs \uac1d\uccb4 \ucd94\uac00",
"what": "spec \ucd5c\uc0c1\uc704\uc5d0 externalDocs \ucd94\uac00",
"why": "\ud3ec\ud138\u00b7\uac00\uc774\ub4dc \ub4f1 \ucd94\uac00 \ubb38\uc11c\ub85c \uac1c\ubc1c\uc790 \uacbd\ud5d8 \ud5a5\uc0c1"
},
"location": "externalDocs",
"message": "\ucd5c\uc0c1\uc704 externalDocs \uac00 \uc5c6\uc2b5\ub2c8\ub2e4",
"message_en": "No top-level externalDocs",
"rule_id": "DOC-004",
"severity": "info"
}
]
}
문제 많은 spec lint — 다수의 error/warning / Lint a spec with multiple issues
{
"action": "lint",
"spec": {
"info": {
"title": "Bad API",
"version": "0.1"
},
"openapi": "3.0.3",
"paths": {
"/userProfile": {
"post": {
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/users": {
"get": {
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/users/{userId}": {
"get": {
"operationId": "getUser",
"operationId2": "dup",
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"servers": [
{
"url": "http://api.example.com"
}
]
}
}
{
"action": "lint",
"by_category": {
"DOC": 2,
"SEC": 3,
"STR": 4,
"VAL": 3
},
"by_severity": {
"error": 4,
"info": 3,
"warning": 5
},
"finding_count": 12
}
보안 문제 spec 감사 / Security audit of an insecure spec
{
"action": "audit_security",
"spec": {
"components": {
"schemas": {
"Login": {
"properties": {
"password": {
"type": "string"
}
},
"type": "object"
}
},
"securitySchemes": {
"ApiKey": {
"in": "query",
"name": "api_key",
"type": "apiKey"
}
}
},
"info": {
"title": "Insecure API",
"version": "1.0.0"
},
"openapi": "3.0.3",
"paths": {
"/data": {
"post": {
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"servers": [
{
"url": "http://api.example.com"
}
]
}
}
{
"action": "audit_security",
"by_severity": {
"error": 3,
"info": 1,
"warning": 1
},
"finding_count": 5,
"overall_risk": "critical",
"passed_rules": [
"SEC-005",
"SEC-006"
],
"risk_label_ko": "\uc704\ud5d8"
}
두 버전 비교 — breaking change 감지 / Compare two versions with breaking changes
{
"action": "compare",
"new_spec": {
"info": {
"title": "API",
"version": "2.0.0"
},
"openapi": "3.0.3",
"paths": {
"/users/{id}": {
"get": {
"operationId": "getUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
},
"old_spec": {
"info": {
"title": "API",
"version": "1.0.0"
},
"openapi": "3.0.3",
"paths": {
"/users": {
"get": {
"operationId": "listUsers",
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/users/{id}": {
"get": {
"operationId": "getUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
}
{
"action": "compare",
"additive_changes": [],
"breaking_changes": [
{
"location": "GET /users",
"type": "endpoint_removed"
},
{
"location": "GET /users/{id}",
"type": "param_type_changed"
}
],
"is_breaking": true,
"summary_ko": "Breaking change 2\uac1c, Additive change 0\uac1c \uac10\uc9c0\ub428"
}
Petstore 스타일 spec 에서 예시 자동 생성 / Auto-generate examples from a Petstore-style spec
{
"action": "generate_examples",
"spec": {
"info": {
"title": "Pet Store",
"version": "1.0.0"
},
"openapi": "3.0.3",
"paths": {
"/pets": {
"post": {
"operationId": "createPet",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"age": {
"type": "integer"
},
"name": {
"type": "string"
},
"species": {
"enum": [
"dog",
"cat",
"bird"
],
"type": "string"
}
},
"required": [
"name",
"species"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"type": "object"
}
}
},
"description": "\uc0dd\uc131\ub428"
}
},
"summary": "\ubc18\ub824\ub3d9\ubb3c \ub4f1\ub85d"
}
}
}
}
}
{
"action": "generate_examples",
"endpoint_examples": [
{
"endpoint": "POST /pets",
"operation_id": "createPet",
"request": {
"body": {
"content_type": "application/json",
"example": {
"age": 1,
"name": "\ud64d\uae38\ub3d9",
"species": "dog"
}
}
},
"responses": [
{
"example": {
"id": 1,
"name": "\ud64d\uae38\ub3d9"
},
"status": "201"
}
]
}
],
"generated_count": 1
}
spec 완성도 점수 측정 / Measure spec completeness score
{
"action": "coverage",
"spec": {
"info": {
"title": "My API",
"version": "1.0.0"
},
"openapi": "3.0.3",
"paths": {
"/items": {
"get": {
"operationId": "listItems",
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
}
{
"action": "coverage",
"areas": {
"description": {
"max_score": 20,
"ratio": 0.0,
"score": 0.0
},
"tags": {
"max_score": 15,
"ratio": 0.0,
"score": 0.0
}
},
"grade": "F",
"grade_ko": "\ubd88\ub7c9",
"recommendations_ko": [
"operation description \uc744 \ucd94\uac00\ud558\uc138\uc694",
"\uac01 operation \uc5d0 tags \ub97c \uc9c0\uc815\ud574 \uadf8\ub8f9\ud654\ud558\uc138\uc694",
"requestBody \ubc0f response \uc5d0 example \uc744 \ucd94\uac00\ud558\uc138\uc694"
],
"score": 28
}
SEC 카테고리만 필터해서 lint / Lint with SEC category filter only
{
"action": "lint",
"categories": [
"SEC"
],
"spec": {
"info": {
"title": "API",
"version": "1.0.0"
},
"openapi": "3.0.3",
"paths": {
"/items": {
"get": {
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"servers": [
{
"url": "https://api.example.com"
}
]
}
}
{
"action": "lint",
"by_category": {
"SEC": 1
},
"by_severity": {
"error": 0,
"info": 0,
"warning": 1
},
"finding_count": 1,
"findings": [
{
"category": "SEC",
"location": "components.securitySchemes",
"message": "securitySchemes \uac00 \uc804\ud600 \uc815\uc758\ub418\uc9c0 \uc54a\uc558\uc2b5\ub2c8\ub2e4",
"rule_id": "SEC-002",
"severity": "warning"
}
]
}
보안 전 항목 통과 — 위험도 없음 / Full security pass with no risk
{
"action": "audit_security",
"spec": {
"components": {
"securitySchemes": {
"BearerAuth": {
"bearerFormat": "JWT",
"scheme": "bearer",
"type": "http"
}
}
},
"info": {
"title": "Secure API",
"version": "1.0.0"
},
"openapi": "3.0.3",
"paths": {
"/data": {
"post": {
"responses": {
"200": {
"description": "OK"
}
},
"security": [
{
"BearerAuth": []
}
]
}
}
},
"security": [
{
"BearerAuth": []
}
],
"servers": [
{
"url": "https://secure.example.com"
}
]
}
}
{
"action": "audit_security",
"finding_count": 1,
"overall_risk": "low",
"passed_rules": [
"SEC-001",
"SEC-002",
"SEC-003",
"SEC-004",
"SEC-005",
"SEC-006"
],
"risk_label_ko": "\ub0ae\uc74c"
}
모든 예시는 에이전트 API로도 조회 가능:
/v1/agent/skills/0ca3f848-b1b6-40c3-8178-b0d23cdaec2a/schema
아직 리뷰가 없습니다. 첫 번째 리뷰를 남겨보세요!