API - część 6

2019-12-19

W dzisiejszej lekcji zobaczymy między innymi: co to jest API, anatomia Check Point Management API R80, metody dostępu do REST API, przykłady wykorzystania.

W dzisiejszej lekcji zobaczymy między innymi:

  • Co to jest API
  • Anatomia Check Point Management API R80
  • Metody dostępu do REST API
  • Przykłady wykorzystania

Wszystkie lekcje są dostępne na portalu CheckMates.

API (Application Programming Interface - interfejs programistyczny aplikacji) jest to sposób komunikacji pomiędzy systemami komputerowymi.

REST (Representational State Transfer - zmiana stanu poprzez reprezentacje) jest to styl architektury oprogramowania opierający się o zbiór wcześniej określonych reguł opisujących, jak definiowane są zasoby, a także umożliwiających dostęp do nich.

HTTP REST API pozwalana na wywołanie standardowych metod HTTP (POST, GET, PUT, DELETE) z wykorzystaniem łącza URL (np. https://<mgmt>/web_api)

Check Point Management API wykorzystuje wyłącznie metodę POST, niezależnie od tego czy chcemy odczytać parametry konfiguracyjne, czy też czy chcemy nanieść w nich zmiany. Natomiast konkretne polecenie zawarte jest w URL:

Dodanie nowego obiektu typu host: POST https://<mgmt-server>:<port>/web_api/add-host

Usunięcie obiektu typu host: POST https://<mgmt-server>:<port>/web_api/delete-host

Zmiana obiektu typu host: POST https://<mgmt-server>:<port>/web_api/set-host

Każde z polecenie zawiera nagłówek (header) oraz ciało (body). W nagłówku obowiązkową właściwością jest: Content-Type: application/json. Jest to informacja, w jakim formacie będą przesyłane szczegóły polecenia. W naszym przypadku JavaScript Object Notation. Drugim obowiązkowym parametrem jest X-chkp-sid (session ID, sid), będącym informacją o uwierzytelnieniu klienta REST API.

W ciele polecenia przekazujemy informację o obiekcie, nad którym chcemy pracować, w przypadku zmiany nowe parametry konfiguracyjne.

Polecenie dodające nowy obiekt, będzie miało następującą postać:

POST https://:/web_api/add-host

    Header:
    content-Type:application/json
    X-chkp-sid:JIroF9ojnh6JCqP6bHHyaJtN3bdOoXYj2OTg-M8eonw
    Body:
    {
        name:webapi-client,
        ip-address:192.0.2.13
    }

Odpowiedź serwera będzie miała podobną konstrukcję.

Przekazane polecenie, przesyłane jest do procesu CPM przez serwer WWW. Proces CPM odpowiada za odczytywanie oraz zapisywanie parametrów z bazy SQL. Od wersji R80 wszystkie obiekty zapisywane są wewnątrz wbudowanej bazy danych Postrgre SQL. W domyślnej konfiguracji serwer API będzie przyjmował polecenia tylko z adresu serwera zarządzającego.

art_6_img_1

Aby komunikować się z innych adresów IP należy w sekcji: Manage & Settings -> Blades -> Managemet API -> Advanced Settings -> Access Setings wybrać odpowiednią opcję (GUI Clients lub All IP Address).

Istnieją cztery metody interakcji z serwerem REST API:

  • HTTP POST (omawiany wcześniej)
  • mgmt_cli - aplikacja dostępna na serwerze MGMT oraz razem z aplikacją SmartConsole
  • CLI SmartConsole - konsola uruchomiana z poziomu SmartConsoli
  • CLI GAIA - CLI dostępne na serwerze zarządzającym

Wszystkie powyższe metody pozwalają na interakcję z serwerem zarządzającym, z tym tą różnicą, że mgmt_cli oraz CLI są aplikacjami wykorzystującymi pierwszą metodą. Każda z tych aplikacji ma swoją składnię, ale komunikacja z serwerem API odbywa się za pomocą poleceń HTTP POST

API Reference Guide znajdziemy pod tym adresem. Znajdziemy tu również przykłady użycia poszczególnych poleceń dla każdej metody dostępu do REST API.

W trakcie pracy za pomocą REST API obowiązują nas te same zasady co w przypadku pracy z SmartConsolą. Na początek musimy się uwierzytelnić. Po uwierzytelnieniu otrzymamy numer identyfikacyjny sesji - wspomniany wcześniej parametr X-chkp-sid. Od tego momentu możemy dokonywać zmian. Pamiętajmy, że identyfikator sesji musi być podany przy każdym żądaniu Naniesione zamiany należy opublikować i ewentualnie zainstalować nową politykę. Po zakończeniu pracy możemy się wylogować.

art_6_img_2

Prześledźmy to na przykładzie mgmt_cli. Wykonujemy polecenie login. Informacja o identyfikatorze sesji zostanie zapisana w pliku id.txt. W następnych poleceniach będziemy wykorzystywać ten plik do przekazania identyfikatora. Bez jego użycia, będziemy musieli uwierzytelnić się przy każdym poleceniu.

    mgmt_cli login user restadmin password Pass1234> id.txt

    mgmt_cli add host name serwer17 ip-address 192.168.10.17 –s id.txt

    mgmt_cli publish –s id.txt

    mgmt_cli logout –s id.txt

Sytuacja w przypadku metody HTTP POST jest identyczna z tym, że identyfikator sesji przekazujemy w nagłówku polecenia.

    POST https://<mgmt-server>:<port>/web_api/login
    {
        "user":" restadmin ",
        "password":"Pass1234"
    }
    POST https://<mgmt-server>:<port>/web_api/add-host
    {
        "name":" serwer17 ",
        "ip-address":"192.168.10.17 "
    }
    POST https://<mgmt-server>:<port>/web_api/publish
    POST https://<mgmt-server>:<port>/web_api/logout

Na aplikację mgmt_cli warto zwrócić uwagę, również z powodu możliwości dodawania wielu obiektów z pliku csv za pomocą jednego polecenia. Możemy również wykorzystać moduł REST API dla ansible i przesyłać polecenia konfiguracyjne zapisane wcześniej w playbooku.

Na koniec zobaczmy jak REST API może zostać wykorzystane w praktyce.

Portal WWW: https://www.youtube.com/watch?v=7wqkNhw2EnQ&feature=youtu.be

Ansible: https://www.youtube.com/watch?v=V11JrNl7pZg&feature=youtu.be

Galeria