Aplikace CISCO ASA REST API

Návod k použití produktu

Nadview

S vydáním Cisco ASA REST API nyní máte další lehkou a snadno použitelnou možnost pro konfiguraci a správu jednotlivých Cisco ASA. ASA REST API je aplikační programovací rozhraní (API) založené na principech RESTful. Lze jej rychle stáhnout a aktivovat na libovolném ASA, kde běží API. Společnost Cisco Systems, Inc.

www.cisco.com

Požadavky a odpovědi ASA REST API

Po instalaci klienta REST do vašeho prohlížeče můžete kontaktovat konkrétního agenta REST společnosti ASA a pomocí standardních metod HTTP získat přístup k aktuálním konfiguračním informacím a vydat další konfigurační parametry.

Pozor: Když je na ASA povoleno rozhraní REST API, připojení jinými protokoly správy zabezpečení nejsou blokována. To znamená, že ostatní uživatelé používající CLI, ASDM nebo Security Manager mohou měnit konfiguraci ASA, zatímco vy děláte totéž.

Struktura požadavku

ASA REST API vám poskytuje programový přístup ke správě jednotlivých ASA prostřednictvím Representational State Transfer (REST) ​​API. Rozhraní API umožňuje externím klientům provádět operace CRUD (Create, Read, Update, Delete) na prostředcích ASA. Všechny požadavky API jsou odesílány přes HTTPS do ASA a je vrácena odpověď.

kde vlastnosti objektu jsou:

Vlastnictví	Typ	Popis
zprávy	Seznam slovníků	Seznam chybových nebo varovných zpráv
kód	Řetězec	Podrobná zpráva odpovídající Error/Warning/Info
podrobnosti	Řetězec	Podrobná zpráva odpovídající Error/Warning/Info

Poznámka: Změny provedené voláním REST API nejsou zachovány ve spouštěcí konfiguraci, ale jsou přiřazeny pouze běžící konfiguraci. Chcete-li uložit změny spouštěcí konfigurace, můžete použít požadavek API POST a write mem. Další informace najdete v položce Write Memory API v obsahu ASA REST API.

Nainstalujte a nakonfigurujte agenta a klienta ASA REST API

Poznámka: REST API Agent je aplikace založená na Javě. Java Runtime Environment (JRE) je součástí balíčku REST API Agent.

Nadview

Pro konfiguraci a správu jednotlivých Cisco ASA je k dispozici několik možností:

• Rozhraní příkazového řádku (CLI) – ovládací příkazy posíláte přímo do ASA přes připojenou konzoli.
• Adaptive Security Device Manager (ASDM) – „on-box“ aplikace pro správu s grafickým uživatelským rozhraním, které můžete použít ke konfiguraci, správě a monitorování ASA.
• Cisco Security Manager – ačkoli je tato grafická aplikace určena pro střední až velké sítě mnoha bezpečnostních zařízení, lze ji použít ke konfiguraci, správě a monitorování jednotlivých ASA.

S vydáním Cisco ASA REST API máte nyní další lehkou a snadno použitelnou možnost. Jedná se o aplikační programovací rozhraní (API), založené na principech „RESTful“, které si můžete rychle stáhnout a aktivovat na libovolném ASA, na kterém API běží.

Po instalaci klienta REST do prohlížeče můžete kontaktovat konkrétního agenta REST společnosti ASA a pomocí standardních metod HTTP získat přístup k aktuálním konfiguračním informacím a vydat další konfigurační parametry.

Pozor: Když je na ASA povoleno rozhraní REST API, připojení jinými protokoly správy zabezpečení nejsou blokována. To znamená, že ostatní uživatelé používající CLI, ASDM nebo Security Manager mohou měnit konfiguraci ASA, zatímco vy děláte totéž.

Požadavky a odpovědi ASA REST API

ASA REST API vám poskytuje programový přístup ke správě jednotlivých ASA prostřednictvím Representational State Transfer (REST) ​​API. API umožňuje externím klientům provádět operace CRUD (Create, Read, Update, Delete) na prostředcích ASA; je založen na protokolu HTTPS a metodologii REST. Všechny požadavky API jsou odesílány přes HTTPS do ASA a je vrácena odpověď. Tato sekce poskytuje přesview o tom, jak jsou požadavky strukturovány, a očekávané odpovědi,

Struktura požadavku

Dostupné způsoby žádosti jsou:

• GET – Načte data ze zadaného objektu.
• PUT – Přidá dodané informace k určenému objektu; vrátí chybu 404 Resource Not Found, pokud objekt neexistuje.
• POST – Vytvoří objekt s dodanými informacemi.
• DELETE – Odstraní zadaný objekt.
• PATCH – Aplikuje dílčí úpravy na zadaný objekt.

Struktura odezvy

• Každý požadavek vytvoří odpověď HTTPS od ASA se standardními záhlavími, obsahem odpovědi a stavovým kódem.

Struktura odpovědi může být:

• LOCATION – ID nově vytvořeného zdroje; pouze pro POST – obsahuje nové ID zdroje (jako reprezentaci URI).
• CONTENT-TYPE – Typ média popisující tělo zprávy odpovědi; popisuje reprezentaci a syntaxi těla zprávy odpovědi.

Každá odpověď obsahuje stav HTTP nebo kód chyby. Dostupné kódy spadají do těchto kategorií:

• 20x – Kód série dvě stě označuje úspěšnou operaci, včetně:
  • 200 OK – Standardní odpověď na úspěšné požadavky.
  • 201 Vytvořeno – požadavek dokončen; vytvořen nový zdroj.
  • 202 Přijato – Požadavek přijat, ale zpracování není dokončeno.
  • 204 Žádný obsah – Server úspěšně zpracoval požadavek; žádný obsah se nevrací.
• 4xx – Čtyřsetový sériový kód označuje chybu na straně klienta, včetně:
  • 400 Špatný požadavek – Neplatné parametry dotazu, včetně nerozpoznaných parametrů, chybějících parametrů nebo neplatných hodnot.
  • 404 Nenalezeno – poskytnuto URL neodpovídá existujícímu zdroji. Napřample, HTTP DELETE může selhat, protože prostředek není dostupný.
  • 405 Metoda není povolena – Byl předložen požadavek HTTP, který není na prostředku povolen; napřample, POST na zdroji pouze pro čtení.
• 5xx – Kód pětisetové řady označuje chybu na straně serveru.

V případě chyby může návratová odpověď kromě kódu chyby obsahovat chybový objekt obsahující další podrobnosti o chybě. Schéma odezvy na chybu/varování JSON je následující:

kde vlastnosti objektu jsou:

Vlastnictví	Typ	Popis
zprávy	Seznam slovníků	Seznam chybových nebo varovných zpráv
kód	Řetězec	Kód chyby/upozornění/informace
podrobnosti	Řetězec	Podrobná zpráva odpovídající Error/Warning/Info

Poznámka: Změny konfigurace ASA provedené voláním REST API nejsou zachovány ve spouštěcí konfiguraci; to znamená, že změny jsou přiřazeny pouze běžící konfiguraci. Chcete-li uložit změny spouštěcí konfigurace, můžete POST požadavek API writemem; pro více informací sledujte položku “Write Memory API” v obsahu ASA REST API.

Nainstalujte a nakonfigurujte agenta a klienta ASA REST API

• Agent REST API je publikován samostatně s dalšími obrázky ASA cisco.com. U fyzických ASA je nutné stáhnout balíček REST API do flash paměti zařízení a nainstalovat pomocí příkazu „rest-api image“. Agent REST API je poté povolen pomocí příkazu „rest-api agent“.
• S virtuálním ASA (ASAv) musí být obraz REST API stažen do oddílu „boot:“. Poté musíte zadat příkaz „rest-api image“ následovaný příkazem „rest-api agent“, abyste získali a povolili agenta REST API.
• Informace o požadavcích a kompatibilitě softwaru a hardwaru REST API naleznete v matici kompatibility Cisco ASA.
• Příslušný balíček REST API pro váš ASA nebo ASAv si můžete stáhnout z software.cisco.com/download/home. Vyhledejte konkrétní model Adaptive Security Appliances (ASA) a poté vyberte Adaptive Security Appliance REST API Plugin.

Poznámka: REST API Agent je aplikace založená na Javě. Java Runtime Environment (JRE) je součástí balíčku REST API Agent.

Pokyny k použití

Důležité Ve všech voláních rozhraní API a existujících skriptech musíte zahrnout záhlaví User-Agent: REST API Agent. Použijte -H 'User-Agent: REST API Agent' pro CURL příkaz. Ve vícekontextovém režimu jsou příkazy REST API Agent dostupné pouze v kontextu systému.

Maximální podporovaná velikost konfigurace

ASA Rest API je „integrovaná“ aplikace běžící uvnitř fyzického ASA a jako taková má omezení paměti, která je jí přidělena. Maximální podporovaná velikost spuštěné konfigurace se během cyklu vydání zvýšila na přibližně 2 MB na nejnovějších platformách, jako jsou 5555 a 5585. ASA Rest API má také omezení paměti na virtuálních platformách ASA. Celková paměť na ASAv5 může být 1.5 GB, zatímco na ASAv10 je to 2 GB. Limity Rest API jsou 450 KB a 500 KB pro ASAv5 a ASAv10.

Uvědomte si proto, že velké spuštěné konfigurace mohou vytvářet výjimky v různých situacích náročných na paměť, jako je velký počet souběžných požadavků nebo velké objemy požadavků. V těchto situacích mohou volání Rest API GET/PUT/POST začít selhávat se zprávami 500 – Internal Server Error a agent Rest API se pokaždé automaticky restartuje. Řešením této situace je buď přesun na platformy ASA/FPR nebo ASAV s vyšší pamětí, nebo zmenšení velikosti běžící konfigurace.

Stáhněte a nainstalujte REST API Agent

Pomocí CLI stáhněte a nainstalujte agenta ASA REST API na konkrétní ASA podle následujících kroků:

• Krok 1: Na požadovaném ASA vydejte kopii disk0: příkaz ke stažení aktuálního balíčku ASA REST API cisco.com do flash paměti ASA.
  • Napřampten: zkopírujte tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA disk0:
• Krok 2: Vydejte obraz rest-api disk0:/ příkaz k ověření a instalaci balíčku.
  • Napřampten: rest-api image disk0:/asa-restapi-111-lfbff-k8.SPA

Instalační program provede kontrolu kompatibility a ověření a poté balíček nainstaluje. ASA se nerestartuje.

Povolte agenta REST API

Chcete-li povolit agenta ASA REST API na konkrétním ASA, postupujte takto:

• Krok 1: Ujistěte se, že je na ASA nainstalován správný obraz softwaru.
  • Nahlédněte do části REST API v matici kompatibility ASA (https://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#pgfId-131643), abyste určili, který obrázek ASA je vyžadován.
• Krok 2: Pomocí CLI se ujistěte, že je HTTP server povolen na ASA a že se klienti API mohou připojit k rozhraní pro správu.
  • Napřampten: Povolit http server
  • http 0.0.0.0 0.0.0.0
• Krok 3: Pomocí CLI definujte HTTP autentizaci pro připojení API. Napřample: aaa autentizace http konzole LOCAL
• Krok 4: Pomocí rozhraní CLI vytvořte statickou trasu v ASA pro provoz API. Napřample: trasa 0.0.0.0 0.0.0.0 1
• Krok 5: Pomocí CLI povolte ASA REST API Agent na ASA. Napřample: agent rest-api

REST API Authentication

Existují dva způsoby ověřování: Základní ověřování HTTP, které předává uživatelské jméno a heslo v každém požadavku, nebo ověřování založené na tokenech se zabezpečeným přenosem HTTPS, které s každým požadavkem předává dříve vytvořený token. V každém případě bude autentizace provedena pro každý požadavek. Další informace o autentizaci na základě tokenů naleznete v části „Token_Authentication_API“ v příručce O ASA REST API v7.14(x).

Poznámka: Na ASA se doporučuje používat certifikáty vydané certifikační autoritou (CA), takže klienti REST API mohou při navazování připojení SSL ověřit certifikáty serveru ASA.

Autorizace příkazů

Pokud je autorizace příkazů nakonfigurována pro použití externího serveru AAA (napřample, aaa autorizační příkaz ), pak musí na tomto serveru existovat uživatel s názvem enable_1 s plnými příkazovými oprávněními. Pokud je autorizace příkazů nakonfigurována pro použití LOCAL databáze ASA (aaa autorizační příkaz LOCAL), musí být všichni uživatelé rozhraní REST API registrováni v databázi LOCAL s úrovněmi oprávnění, které odpovídají jejich rolím:

• K vyvolání požadavků na monitorování je vyžadována úroveň oprávnění 3 nebo vyšší.
• Pro vyvolání požadavků GET je vyžadována úroveň oprávnění 5 nebo vyšší.
• Úroveň oprávnění 15 je nezbytná pro vyvolání operací PUT/POST/DELETE.

Nakonfigurujte svého klienta REST API

Chcete-li nainstalovat a nakonfigurovat klienta REST API v prohlížeči místního hostitele, postupujte takto:

• Krok 1: Získejte a nainstalujte klienta REST API pro váš prohlížeč.
  • Pro Chrome nainstalujte klienta REST od Googlu. Pro Firefox nainstalujte doplněk RESTClient. Internet Explorer není podporován.
• Krok 2: Pomocí prohlížeče spusťte následující požadavek: https: /api/objects/networkobjects
  • Pokud obdržíte nechybovou odpověď, dosáhli jste agenta REST API fungujícího na ASA.
  • Pokud máte problémy s požadavkem agenta, můžete povolit zobrazení informací o ladění na konzole CLI, jak je popsáno v části Povolení ladění REST API na ASA.
• Krok 3: Volitelně můžete otestovat připojení k ASA provedením operace POST.

Napřampten: Poskytněte základní autorizační údaje ( ), nebo ověřovací token (další informace viz Ověření tokenu).

• Cílová adresa požadavku: https://<asa management ipaddress>/api/objects/networkobjects
• Typ obsahu těla: app/json

Surové tělo operace:

Nyní můžete použít ASA REST API ke konfiguraci a monitorování ASA. Popisy volání naleznete v dokumentaci API a napřamples.

O úplném obnovení záložní konfigurace

Obnovení úplné záložní konfigurace na ASA pomocí REST API znovu načte ASA. Chcete-li se tomu vyhnout, použijte k obnovení záložní konfigurace následující příkaz:

• {
  • “příkazy”:[”copy /noconfirm disk0:/filename> running-config”]
• }
  • Kdefilename> je backup.cfg nebo jakýkoli název, který jste použili při zálohování konfigurace.

Konzola dokumentace a exportování skriptů API

Můžete také použít online dokumentační konzolu REST API (označovanou jako „uživatelské rozhraní dokumentu“), která je k dispozici na adrese host:port/doc/ jako „sandbox“, abyste se dozvěděli a vyzkoušeli volání API přímo na ASA. Dále můžete použít tlačítko Export Operation v uživatelském rozhraní dokumentu k uložení zobrazené metody, napřample jako skript JavaScript, Python nebo Perl file vašemu místnímu hostiteli. Tento skript pak můžete použít na své ASA a upravit jej pro použití v jiných ASA a dalších síťových zařízeních. To znamenalo především jako vzdělávací a bootstrapingový nástroj.

JavaScript

• Pomocí JavaScriptu file vyžaduje instalaci node.js, který lze nalézt na http://nodejs.org/.
• Pomocí node.js můžete spustit JavaScript file, obvykle napsaný pro prohlížeč, jako skript příkazového řádku. Jednoduše postupujte podle pokynů k instalaci a poté spusťte skript s node script.js.

Krajta

• Python skripty vyžadují, abyste si nainstalovali Python, dostupný z https://www.python.org/.
• Jakmile nainstalujete Python, můžete skript spustit s heslem uživatelského jména python script.py.

Perl

Používání skriptů v Perlu vyžaduje nějaké další nastavení – potřebujete pět komponent: samotný Perl a čtyři knihovny Perlu:

• Balíček Perl, nalezený na http://www.perl.org/
• Balíček::CPAN, naleznete na adrese http://search.cpan.org/~andk/Bundle-CPAN-1.861/CPAN.pm
• ODPOČINEK::Klient, nalezen na http://search.cpan.org/~mcrawfor/REST-Client-88/lib/REST/Client.pm
• MIM::Base64, najdete na http://perldoc.perl.org/MIME/Base64.html
• JSON, nalezený na http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm

Tady je exampsoubor bootstrapping Perl na počítači Macintosh:

• $ sudo perl -MCPAN e shell
• cpan> install Bundle::CPAN
• cpan> nainstalovat REST:: Klient
• cpan> nainstalovat MIME::Základ 64
• cpan> nainstalovat JSON

Po instalaci závislostí můžete spustit skript pomocí perl script.pl uživatelské jméno heslo.

Povolení ladění REST API na ASA

Pokud máte problémy s konfigurací nebo připojením k REST API na ASA, můžete pomocí následujícího příkazu CLI povolit zobrazení ladicích zpráv na vaší konzole. Pro zakázání ladicích zpráv použijte příkaz no.
debug rest-api [agent | cli | klient | démon | proces | token-auth] [chyba | event] no debug rest-api

Popis syntaxe

• činidlo: (Volitelné) Povolte informace o ladění agenta REST API.
• cli: (Volitelné) Povolte zprávy ladění pro komunikaci mezi démonem a agentem rozhraní REST API CLI.
• klient: (Volitelné) Povolte informace o ladění pro směrování zpráv mezi klientem REST API a agentem REST API.
• démon: (Volitelné) Povolte zprávy ladění pro komunikaci mezi démonem a agentem REST API.
• proces: (Volitelné) Povolte informace o spuštění/zastavení procesu ladění agenta REST API.
• token-auth: (Volitelné) Informace o ladění autentizace pomocí tokenu REST API.
• chyba: (Volitelné) Toto klíčové slovo použijte k omezení ladění zpráv pouze na chyby zaznamenané rozhraním API.
• událost: (Volitelné) Toto klíčové slovo použijte k omezení ladění zpráv pouze na události zaznamenané rozhraním API.

Pokyny k použití

Pokud nezadáte konkrétní klíčové slovo komponenty (tj. pokud jednoduše zadáte příkaz debug rest-api), zobrazí se ladicí zprávy pro všechny typy komponent. Pokud nezadáte klíčové slovo událost ani chyba, zobrazí se pro zadanou komponentu událost i chybové zprávy. Napřample, událost debug rest-api daemon zobrazí pouze zprávy o ladění událostí pro komunikaci API Daemon-to-Agent.

Související příkazy

Příkaz / Popis

• ladění HTTP; Použijte tento příkaz k view podrobné informace o HTTP provozu.

Zprávy Syslog související s ASA REST API

V této části jsou popsány zprávy systémového protokolu související s ASA REST API.

342001

• Chybová zpráva: %ASA-7-342001: Agent REST API byl úspěšně spuštěn.
  • Vysvětlení: Agent REST API musí být úspěšně spuštěn, než klient REST API může nakonfigurovat ASA.
  • Doporučená akce: Žádný.

342002

• Chybová zpráva: %ASA-3-342002: Agent REST API selhal, důvod: důvod
  • Vysvětlení: Agent REST API se může z různých důvodů nepodařit spustit nebo selhat a důvod je uveden.
  • důvod – příčina selhání rozhraní REST API

Doporučená akce: Akce provedené k vyřešení problému se liší v závislosti na zaznamenaném důvodu. Napřample, REST API Agent se zhroutí, když procesu Java dojde paměť. Pokud k tomu dojde, musíte restartovat agenta REST API. Pokud restart není úspěšný, kontaktujte Cisco TAC a zjistěte hlavní příčinu opravy.

342003

• Chybová zpráva: %ASA-3-342003: Bylo přijato oznámení o selhání agenta REST API. Agent bude automaticky restartován.
  • Vysvětlení: Bylo přijato oznámení o selhání od agenta REST API a probíhá pokus o restartování agenta.
  • Doporučená akce: Žádný.

342004

• Chybová zpráva: %ASA-3-342004: Po 5 neúspěšných pokusech se nepodařilo automaticky restartovat agenta REST API. Pomocí příkazů 'no rest-api agent' a 'rest-api agent' ručně restartujte agenta.
  • Vysvětlení: Agent REST API se po mnoha pokusech nepodařilo spustit.
  • Doporučená akce: Chcete-li lépe porozumět příčině selhání, podívejte se na syslog %ASA-3-342002 (pokud je přihlášen). Zkuste zakázat agenta REST API zadáním příkazu no rest-api agent a znovu aktivovat agenta REST API pomocí příkazu rest-api agent.

Související dokumentace

Chcete-li získat další informace o ASA a její konfiguraci a správě, použijte následující odkaz:

• Navigace v dokumentaci Cisco ASA Series: http://www.cisco.com/go/asadocs
• Použijte následující odkaz view seznam funkcí ASA, které nejsou podporovány na ASAv: http://www.cisco.com/c/en/us/td/docs/security/asa/asa92/configuration/general/asa-general-cli/introasav.html#pgfId-1156883

Tento dokument je třeba používat ve spojení s dokumenty dostupnými v části „Související dokumentace“.
Cisco a logo Cisco jsou ochranné známky nebo registrované ochranné známky společnosti Cisco a/nebo jejích přidružených společností v USA a dalších zemích. Na view seznam ochranných známek Cisco, přejděte sem URL: Www.cisco.com/go/trademarks. Uvedené ochranné známky třetích stran jsou majetkem příslušných vlastníků. Použití slova partner neznamená partnerský vztah mezi společností Cisco a jakoukoli jinou společností. (1721R)
Žádné adresy a telefonní čísla internetového protokolu (IP) použité v tomto dokumentu nejsou zamýšleny jako skutečné adresy a telefonní čísla. Jakýkoli exampsoubory, výstup příkazového displeje, schémata topologie sítě a další obrázky zahrnuté v dokumentu jsou uvedeny pouze pro ilustrativní účely.
Jakékoli použití skutečných IP adres nebo telefonních čísel v ilustrativním obsahu je neúmyslné a náhodné.

Společnost Cisco Systems, Inc.

• www.cisco.com

© 2014-2018 Cisco Systems, Inc. Všechna práva vyhrazena.

Dokumenty / zdroje

Aplikace CISCO ASA REST API [pdfUživatelská příručka Aplikace ASA REST API, ASA, aplikace REST API, aplikace API, aplikace

Reference

• Uživatelská příručka