CISCO ASA REST API 앱 사용자 가이드

내용물 숨다

1 CISCO ASA REST API 앱

2 제품 사용 지침

3 위에view

4 ASA REST API 요청 및 응답

5 ASA REST API 에이전트 및 클라이언트 설치 및 구성

6 문서 콘솔 및 API 스크립트 내보내기

7 ASA에서 REST API 디버깅 활성화

8 ASA REST API 관련 Syslog 메시지

9 관련 문서

10 문서 / 리소스

10.1 참고문헌

CISCO ASA REST API 앱

제품 사용 지침

위에view

Cisco의 ASA REST API가 출시됨에 따라 이제 개별 Cisco ASA를 구성하고 관리하기 위한 또 다른 가볍고 사용하기 쉬운 옵션이 있습니다. ASA REST API는 RESTful 원칙에 기반한 애플리케이션 프로그래밍 인터페이스(API)입니다. API가 실행되는 모든 ASA에서 빠르게 다운로드하여 활성화할 수 있습니다. Cisco Systems, Inc.

www.cisco.com

ASA REST API 요청 및 응답

브라우저에 REST 클라이언트를 설치한 후에는 특정 ASA의 REST 에이전트에 접속하여 표준 HTTP 메서드를 사용하여 현재 구성 정보에 액세스하고 추가 구성 매개변수를 발행할 수 있습니다.

주의: ASA에서 REST API가 활성화되면 다른 보안 관리 프로토콜의 연결이 차단되지 않습니다. 즉, CLI, ASDM 또는 Security Manager를 사용하는 다른 사람이 동일한 작업을 수행하는 동안 ASA 구성을 변경할 수 있습니다.

요청 구조

ASA REST API는 Representational State Transfer(REST) API를 통해 개별 ASA를 관리하는 프로그래밍 방식 액세스를 제공합니다. 이 API를 통해 외부 클라이언트는 ASA 리소스에서 CRUD(Create, Read, Update, Delete) 작업을 수행할 수 있습니다. 모든 API 요청은 HTTPS를 통해 ASA로 전송되고 응답이 반환됩니다.

개체 속성은 다음과 같습니다.

재산	유형	설명
메시지	사전 목록	오류 또는 경고 메시지 목록
암호	끈	오류/경고/정보에 해당하는 자세한 메시지
세부	끈	오류/경고/정보에 해당하는 자세한 메시지

메모: REST API 호출로 변경한 내용은 시작 구성에 유지되지 않고 실행 중인 구성에만 할당됩니다. 시작 구성에 대한 변경 내용을 저장하려면 POST a write mem API 요청을 사용할 수 있습니다. 자세한 내용은 ASA REST API 목차에 있는 Write Memory API 항목을 참조하십시오.

ASA REST API 에이전트 및 클라이언트 설치 및 구성

메모: REST API Agent는 Java 기반 애플리케이션입니다. Java Runtime Environment(JRE)는 REST API Agent 패키지에 번들로 제공됩니다.

위에view

개별 Cisco ASA를 구성하고 관리하기 위해 사용할 수 있는 옵션은 다음과 같습니다.

명령줄 인터페이스(CLI) – 연결된 콘솔을 통해 ASA에 직접 제어 명령을 보냅니다.

ASDM(Adaptive Security Device Manager) – ASA를 구성, 관리 및 모니터링하는 데 사용할 수 있는 그래픽 사용자 인터페이스가 있는 "온박스" 관리 애플리케이션입니다.
Cisco Security Manager는 중대형 규모의 여러 보안 장치로 구성된 네트워크를 대상으로 하지만, 이 그래픽 애플리케이션은 개별 ASA를 구성, 관리, 모니터링하는 데 사용할 수 있습니다.

Cisco의 ASA REST API가 출시됨에 따라 이제 가볍고 사용하기 쉬운 또 다른 옵션이 있습니다. 이것은 "RESTful" 원칙을 기반으로 하는 애플리케이션 프로그래밍 인터페이스(API)로, API가 실행되는 모든 ASA에서 빠르게 다운로드하여 활성화할 수 있습니다.

ASA REST API 요청 및 응답

ASA REST API는 Representational State Transfer(REST) API를 통해 개별 ASA를 관리하는 프로그래밍 방식 액세스를 제공합니다. 이 API는 외부 클라이언트가 ASA 리소스에서 CRUD(Create, Read, Update, Delete) 작업을 수행할 수 있도록 허용합니다. 이는 HTTPS 프로토콜과 REST 방법론을 기반으로 합니다. 모든 API 요청은 HTTPS를 통해 ASA로 전송되고 응답이 반환됩니다. 이 섹션에서는view 요청이 어떻게 구성되는지, 그리고 예상되는 응답에 대해

요청 구조

사용 가능한 요청 방법은 다음과 같습니다.

GET – 지정된 객체에서 데이터를 검색합니다.
PUT – 제공된 정보를 지정된 객체에 추가합니다. 객체가 존재하지 않으면 404 리소스를 찾을 수 없음 오류를 반환합니다.

POST – 제공된 정보로 객체를 생성합니다.
DELETE – 지정된 개체를 삭제합니다.

PATCH – 지정된 개체에 부분적인 수정 사항을 적용합니다.

응답 구조

각 요청은 표준 헤더, 응답 내용 및 상태 코드가 포함된 HTTPS 응답을 ASA에서 생성합니다.

응답 구조는 다음과 같습니다.

LOCATION – 새로 생성된 리소스 ID. POST에만 해당. 새 리소스 ID를 보관합니다(URI 표현으로).
CONTENT-TYPE – 응답 메시지 본문을 설명하는 미디어 유형입니다. 응답 메시지 본문의 표현 및 구문을 설명합니다.

각 응답에는 HTTP 상태 또는 오류 코드가 포함됩니다. 사용 가능한 코드는 다음 범주에 속합니다.

20x – XNUMX 시리즈 코드는 다음을 포함하여 성공적인 작업을 나타냅니다.
- 200 OK – 성공적인 요청에 대한 표준 응답입니다.
- 201 생성됨 – 요청이 완료되었습니다. 새로운 리소스가 생성되었습니다.
- 202 승인됨 – 요청이 승인되었지만 처리가 완료되지 않았습니다.
- 204 콘텐츠 없음 – 서버가 요청을 성공적으로 처리했지만 콘텐츠가 반환되지 않았습니다.
4xx – XNUMX 시리즈 코드는 다음을 포함한 클라이언트 측 오류를 나타냅니다.
- 400 잘못된 요청 – 인식할 수 없는 매개변수, 누락된 매개변수 또는 잘못된 값을 포함한 잘못된 쿼리 매개변수입니다.
- 404 찾을 수 없음 – 제공된 URL 기존 리소스와 일치하지 않습니다. 예를 들어ampHTTP DELETE는 리소스를 이용할 수 없기 때문에 실패할 수 있습니다.
- 405 허용되지 않는 메서드 - 리소스에서 허용되지 않는 HTTP 요청이 제공되었습니다. 예를 들어ample, 읽기 전용 리소스에 대한 POST.
5xx – XNUMX 시리즈 코드는 서버 측 오류를 나타냅니다.

오류의 경우, 오류 코드 외에도 반환 응답에는 오류에 대한 자세한 내용을 포함하는 오류 객체가 포함될 수 있습니다. JSON 오류/경고 응답 스키마는 다음과 같습니다.

개체 속성은 다음과 같습니다.

재산	유형	설명
메시지	사전 목록	오류 또는 경고 메시지 목록
암호	끈	오류/경고/정보 코드
세부	끈	오류/경고/정보에 해당하는 자세한 메시지

메모: REST API 호출로 ASA 구성에 대한 변경 사항은 시작 구성에 유지되지 않습니다. 즉, 변경 사항은 실행 중인 구성에만 할당됩니다. 시작 구성에 대한 변경 사항을 저장하려면 writemem API 요청을 POST할 수 있습니다. 자세한 내용은 ASA REST API 목차에 있는 "Write Memory API" 항목을 따르십시오.

ASA REST API 에이전트 및 클라이언트 설치 및 구성

REST API 에이전트는 다른 ASA 이미지와 함께 개별적으로 게시됩니다. 시스코닷컴. 물리적 ASA의 경우 REST API 패키지를 장치의 플래시에 다운로드하고 "rest-api image" 명령을 사용하여 설치해야 합니다. 그런 다음 REST API 에이전트를 "rest-api agent" 명령을 사용하여 활성화합니다.
가상 ASA(ASAv)를 사용하면 REST API 이미지를 "boot:" 파티션에 다운로드해야 합니다. 그런 다음 "rest-api image" 명령을 실행한 다음 "rest-api agent" 명령을 실행하여 REST API 에이전트에 액세스하고 활성화해야 합니다.
REST API 소프트웨어 및 하드웨어 요구 사항과 호환성에 대한 자세한 내용은 Cisco ASA 호환성 매트릭스를 참조하세요.

ASA 또는 ASAv에 적합한 REST API 패키지를 다음에서 다운로드할 수 있습니다. Software.cisco.com/download/home. 특정 Adaptive Security Appliances(ASA) 모델을 찾은 다음 Adaptive Security Appliance REST API 플러그인을 선택합니다.

메모: REST API Agent는 Java 기반 애플리케이션입니다. Java Runtime Environment(JRE)는 REST API Agent 패키지에 번들로 제공됩니다.

사용 지침

중요 모든 API 호출 및 기존 스크립트에 헤더 User-Agent: REST API Agent를 포함해야 합니다. C에 대해 -H 'User-Agent: REST API Agent'를 사용합니다.URL 명령. 다중 컨텍스트 모드에서 REST API 에이전트 명령은 시스템 컨텍스트에서만 사용할 수 있습니다.

최대 지원 구성 크기

ASA Rest API는 물리적 ASA 내부에서 실행되는 "온보드" 애플리케이션이며, 따라서 할당된 메모리에 제한이 있습니다. 지원되는 최대 실행 구성 크기는 릴리스 주기 동안 2 및 5555와 같은 최신 플랫폼에서 약 5585MB로 증가했습니다. ASA Rest API는 가상 ASA 플랫폼에서도 메모리 제약이 있습니다. ASAv5의 총 메모리는 1.5GB가 될 수 있는 반면, ASAv10에서는 2GB입니다. Rest API 제한은 ASAv450와 ASAv500의 경우 각각 5KB와 10KB입니다.

따라서 대규모 실행 구성은 동시 요청이 많거나 요청 볼륨이 큰 등 다양한 메모리 집약적 상황에서 예외를 생성할 수 있다는 점을 알아두십시오. 이러한 상황에서 Rest API GET/PUT/POST 호출은 500 - Internal Server Error 메시지와 함께 실패하기 시작할 수 있으며, Rest API 에이전트는 매번 자동으로 다시 시작됩니다. 이 상황에 대한 해결 방법은 더 높은 메모리 ASA/FPR 또는 ASAV 플랫폼으로 이동하거나 실행 구성의 크기를 줄이는 것입니다.

REST API 에이전트 다운로드 및 설치

CLI를 사용하여 다음 단계에 따라 특정 ASA에 ASA REST API 에이전트를 다운로드하고 설치하세요.

1단계: 원하는 ASA에서 사본을 발급합니다. disk0: 현재 ASA REST API 패키지를 다운로드하는 명령 시스코닷컴 ASA의 플래시 메모리로.
- 예를 들어amp르 : tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA를 디스크0에 복사하세요:
2단계: rest-api 이미지 disk0:/를 발급합니다. 패키지를 확인하고 설치하는 명령입니다.
- 예를 들어amp르 : rest-api 이미지 disk0:/asa-restapi-111-lfbff-k8.SPA

설치 프로그램은 호환성 및 유효성 검사를 수행한 다음 패키지를 설치합니다. ASA는 재부팅하지 않습니다.

REST API 에이전트 활성화

특정 ASA에서 ASA REST API 에이전트를 활성화하려면 다음 단계를 따르세요.

1단계: ASA에 올바른 소프트웨어 이미지가 설치되어 있는지 확인하세요.
- ASA 호환성 매트릭스의 REST API 섹션을 참조하세요.https://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#pgfId-131643) 어떤 ASA 이미지가 필요한지 확인합니다.

2단계: CLI를 사용하여 ASA에서 HTTP 서버가 활성화되어 있는지 확인하고 API 클라이언트가 관리 인터페이스에 연결할 수 있는지 확인합니다.
- 예를 들어amp르 : http 서버 활성화
- http 0.0.0.0 0.0.0.0

3단계: CLI를 사용하여 API 연결에 대한 HTTP 인증을 정의합니다. 예를 들어ample: aaa 인증 http 콘솔 LOCAL
4단계: CLI를 사용하여 API 트래픽에 대한 ASA에서 정적 경로를 만듭니다. 예를 들어ample: 경로 0.0.0.0 0.0.0.0 1
5단계: CLI를 사용하여 ASA에서 ASA REST API 에이전트를 활성화합니다. 예를 들어ample: rest-api 에이전트

REST API 인증

인증에는 두 가지 방법이 있습니다. 모든 요청에서 사용자 이름과 비밀번호를 전달하는 기본 HTTP 인증 또는 각 요청에서 이전에 생성된 토큰을 전달하는 보안 HTTPS 전송을 통한 토큰 기반 인증입니다. 어느 쪽이든 모든 요청에 대해 인증이 수행됩니다. 토큰 기반 인증에 대한 추가 정보는 ASA REST API v7.14(x) 가이드의 "Token_Authentication_API" 섹션을 참조하십시오.

메모: ASA에서는 인증 기관(CA)에서 발급한 인증서를 사용하는 것이 좋습니다. 이렇게 하면 REST API 클라이언트가 SSL 연결을 설정할 때 ASA 서버 인증서의 유효성을 검사할 수 있습니다.

명령 권한 부여

명령 권한이 외부 AAA 서버를 사용하도록 구성된 경우(예:ample, aaa 권한 명령 ), 그러면 enable_1이라는 사용자가 전체 명령 권한을 가진 해당 서버에 있어야 합니다. 명령 권한이 ASA의 LOCAL 데이터베이스를 사용하도록 구성된 경우(aaa 권한 명령 LOCAL), 모든 REST API 사용자는 역할에 적합한 권한 수준으로 LOCAL 데이터베이스에 등록되어야 합니다.

모니터링 요청을 호출하려면 3 이상의 권한 수준이 필요합니다.

GET 요청을 호출하려면 5 이상의 권한 수준이 필요합니다.
PUT/POST/DELETE 작업을 호출하려면 권한 수준 15가 필요합니다.

REST API 클라이언트 구성

로컬 호스트 브라우저에 REST API 클라이언트를 설치하고 구성하려면 다음 단계를 따르세요.

1단계: 브라우저에 대한 REST API 클라이언트를 구입하여 설치합니다.
- Chrome의 경우 Google에서 REST 클라이언트를 설치합니다. Firefox의 경우 RESTClient 애드온을 설치합니다. Internet Explorer는 지원되지 않습니다.

2단계: 브라우저를 사용하여 다음 요청을 시작하세요: https: /api/객체/네트워크객체
- 오류가 아닌 응답을 받으면 ASA에서 작동하는 REST API 에이전트에 접속한 것입니다.
- 에이전트 요청에 문제가 있는 경우 ASA에서 REST API 디버깅 활성화에 설명된 대로 CLI 콘솔에서 디버깅 정보 표시를 활성화할 수 있습니다.

3단계: 원하는 경우 POST 작업을 수행하여 ASA에 대한 연결을 테스트할 수 있습니다.

예를 들어amp르 : 기본 권한 부여 자격 증명 제공 ( ), 또는 인증 토큰(자세한 내용은 토큰 인증 참조).

대상 요청 주소: https://<asa management ipaddress>/api/objects/networkobjects

본문 내용 유형: 응용 프로그램 / json

작업의 원본 본문:

이제 ASA REST API를 사용하여 ASA를 구성하고 모니터링할 수 있습니다. 호출 설명 및 ex에 대한 API 설명서를 참조하세요.amp레.

백업 구성을 완전히 복원하는 것에 관하여

REST API를 사용하여 ASA에서 전체 백업 구성을 복원하면 ASA가 다시 로드됩니다. 이를 방지하려면 다음 명령을 사용하여 백업 구성을 복원합니다.

{
- “명령”:[“copy /noconfirm disk0:/file이름> 실행 구성”]
}
- 어디filename>은 backup.cfg이거나 구성을 백업할 때 사용한 이름입니다.

문서 콘솔 및 API 스크립트 내보내기

또한 REST API 온라인 문서 콘솔(일명 "Doc UI")을 host:port/doc/에서 사용할 수 있으며, ASA에서 직접 API 호출에 대해 알아보고 시도할 수 있는 "샌드박스"로 사용할 수 있습니다. 또한 Doc UI의 Export Operation 버튼을 사용하여 표시된 메서드를 저장할 수 있습니다.ampJavaScript, Python 또는 Perl 스크립트로서의 le file 로컬 호스트에. 그런 다음 이 스크립트를 ASA에 적용하고 다른 ASA 및 다른 네트워크 장치에 적용하기 위해 편집할 수 있습니다. 이는 주로 교육 및 부트스트래핑 도구로 사용됩니다.

자바스크립트

자바스크립트 사용 file node.js 설치가 필요합니다. 여기에서 찾을 수 있습니다. http://nodejs.org/.
node.js를 사용하면 JavaScript를 실행할 수 있습니다. file, 일반적으로 브라우저용으로 작성되며 명령줄 스크립트와 같습니다. 설치 지침을 따르고 node script.js로 스크립트를 실행하기만 하면 됩니다.

파이썬

Python 스크립트를 사용하려면 Python을 설치해야 합니다. https://www.python.org/.
Python을 설치한 후 python script.py 사용자 이름 비밀번호로 스크립트를 실행할 수 있습니다.

펄

Perl 스크립트를 사용하려면 몇 가지 추가 설정이 필요합니다. Perl 자체와 Perl 라이브러리 4개 등 5가지 구성 요소가 필요합니다.

Perl 패키지는 다음에서 찾을 수 있습니다. http://www.perl.org/
묶음::CPAN은 http://search.cpan.org/~andk/Bundle-CPAN-1.861/CPAN.pm에서 찾을 수 있습니다.

나머지::클라이언트, 발견됨 http://search.cpan.org/~mcrawfor/REST-Client-88/lib/REST/Client.pm
몸짓 광대극::Base64는 다음에서 발견되었습니다. http://perldoc.perl.org/MIME/Base64.html
JSON은 다음에서 찾을 수 있습니다. http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm

여기 전직이 있습니다ampMacintosh에서 Perl 부트스트래핑의 le:

$ sudo perl -MCPAN e 쉘
cpan> 번들 설치::씨펜

cpan> REST 설치:: 고객
cpan> MIME 설치::베이스64
cpan> JSON 설치

종속성을 설치한 후에는 perl script.pl 사용자 이름 비밀번호를 사용하여 스크립트를 실행할 수 있습니다.

ASA에서 REST API 디버깅 활성화

구문 설명

대리인: (선택 사항) REST API 에이전트 디버깅 정보를 활성화합니다.
클릭: (선택 사항) REST API CLI 데몬-에이전트 통신에 대한 디버깅 메시지를 활성화합니다.
고객: (선택 사항) REST API 클라이언트와 REST API 에이전트 간 메시지 라우팅에 대한 디버깅 정보를 활성화합니다.

악마: (선택 사항) REST API 데몬-에이전트 통신에 대한 디버깅 메시지를 활성화합니다.
프로세스: (선택 사항) REST API 에이전트 프로세스 시작/중지 디버깅 정보를 활성화합니다.
토큰 인증: (선택 사항) REST API 토큰 인증 디버깅 정보.

오류: (선택 사항) 이 키워드를 사용하면 API에서 기록된 오류로만 디버그 메시지를 제한할 수 있습니다.
이벤트: (선택 사항) 이 키워드를 사용하면 디버그 메시지를 API에서 기록한 이벤트로만 제한할 수 있습니다.

사용 지침

특정 구성 요소 키워드를 제공하지 않으면(즉, 단순히 debug rest-api 명령을 실행하면) 모든 구성 요소 유형에 대한 디버그 메시지가 표시됩니다. 이벤트 또는 오류 키워드를 제공하지 않으면 지정된 구성 요소에 대한 이벤트 및 오류 메시지가 모두 표시됩니다. 예를 들어ample, debug rest-api daemon event는 API Daemon-to-Agent 통신에 대한 이벤트 디버그 메시지만 표시합니다.

관련 명령

명령어 / 설명

HTTP 디버그; 이 명령을 사용하여 view HTTP 트래픽에 대한 자세한 정보.

ASA REST API 관련 Syslog 메시지

이 섹션에서는 ASA REST API 관련 시스템 로그 메시지에 대해 설명합니다.

342001

오류 메시지: %ASA-7-342001: REST API 에이전트가 성공적으로 시작되었습니다.
- 설명: REST API 클라이언트가 ASA를 구성하려면 REST API 에이전트가 성공적으로 시작되어야 합니다.
- 권장 조치: 없음.

342002

오류 메시지: %ASA-3-342002: REST API 에이전트가 실패했습니다. 이유: reason
- 설명: REST API 에이전트는 다양한 이유로 시작되지 않거나 충돌할 수 있으며 그 이유는 명시되어 있습니다.
- reason—REST API 실패의 원인

권장 조치: 문제를 해결하기 위해 취한 조치는 기록된 이유에 따라 다릅니다. 예를 들어ample, Java 프로세스가 메모리를 소진하면 REST API 에이전트가 충돌합니다. 이런 경우 REST API 에이전트를 다시 시작해야 합니다. 다시 시작이 성공적이지 않으면 Cisco TAC에 문의하여 근본 원인 수정 사항을 파악합니다.

342003

오류 메시지: %ASA-3-342003: REST API 에이전트 실패 알림이 수신되었습니다. 에이전트가 자동으로 다시 시작됩니다.
- 설명: REST API 에이전트로부터 실패 알림을 받았고 에이전트를 다시 시작하려고 시도하고 있습니다.
- 권장 조치: 없음.

342004

오류 메시지: %ASA-3-342004: 5번의 실패 시도 후 REST API 에이전트를 자동으로 다시 시작하는 데 실패했습니다. 'no rest-api agent' 및 'rest-api agent' 명령을 사용하여 에이전트를 수동으로 다시 시작하세요.
- 설명: REST API 에이전트가 여러 번 시도되었지만 시작하지 못했습니다.
- 권장 조치: 실패의 이유를 더 잘 이해하려면 syslog %ASA-3-342002(로그된 경우)를 참조하세요. no rest-api agent 명령을 입력하여 REST API 에이전트를 비활성화하고 rest-api agent 명령을 사용하여 REST API 에이전트를 다시 활성화해 보세요.

문서 / 리소스

CISCO ASA REST API 앱 [PDF 파일] 사용자 가이드
ASA REST API 앱, ASA, REST API 앱, API 앱, 앱

참고문헌

사용자 설명서