Halaman ini diterjemahkan oleh Cloud Translation API.

API skor dan profil keamanan

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Ringkasan

Halaman ini menjelaskan cara mengelola skor keamanan dan profil keamanan Penilaian Risiko (juga disebut sebagai "profil") menggunakan API. Halaman ini menampilkan contoh permintaan API.

Untuk ringkasan fungsi Penilaian Risiko, termasuk batasan, dan petunjuk untuk menggunakan UI, lihat Ringkasan dan UI penilaian risiko.

Contoh Risk Assessment v2 API

Parameter untuk contoh API v2

Contoh di bagian ini dapat menggunakan parameter berikut:

ORG adalah organisasi Anda.
ENV adalah lingkungan tempat Anda ingin skor dihitung.
PROFILE_ID adalah nama profil. PROFILE_ID dapat berupa google-default atau nama profil kustom yang Anda buat.
PROFILE_DESC (opsional) adalah deskripsi untuk profil. Deskripsi ini harus berupa deskripsi profil yang dapat dibaca manusia dan memberikan informasi yang cukup untuk membedakannya dari profil lain.
PROXY_NAME: Nama proxy.
$TOKEN adalah variabel lingkungan untuk token akses OAuth.

Mengambil hasil penilaian keamanan batch

Pengguna dengan peran Security Admin atau Security Viewer memiliki izin untuk melakukan komputasi penilaian risiko ad hoc. Anda harus menentukan profil keamanan, cakupan (lingkungan Apigee), dan resource yang akan dinilai. Resource dapat berupa include_all_resources: true untuk melakukan komputasi pada semua resource dalam cakupan, atau hanya beberapa. Lihat securityAssessmentResults.batchCompute dalam dokumentasi referensi Apigee Management API untuk mengetahui informasi selengkapnya tentang fungsi ini.

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityAssessmentResults:batchCompute" \
  -X POST \
  -H "Authorization: Bearer $TOKEN"
  -H 'Content-type: application/json' \
  -d '{
    "profile": "google-default",
    "scope": "ENV",
    "include_all_resources": {}
  }'

Berikut adalah respons potensial untuk permintaan tersebut:

  {
    "security_assessment_results": [
      {
        "resource": {
          "name" : "my-proxy-1",
          "revision": "1"
        },
        "create_time": "2023-11-22T03:04:05Z",
        "score": 99,
        "severity": "low",
        "failed_assessment_by_weight": {
          "MINOR": 1
        },
        "assessment_recommendations": {
          "CORS-Check": {
            "weight": "MINOR",
            "recommendations": [
              {
                "description": "add CORS policy to your proxy",
                "learn_more_link": "https://example.com"
              }
            ]
          }
        }
      },
      {
        "resource": {
          "name" : "my-proxy-2",
          "revision": "3"
        },
        "create_time": "2023-11-22T03:04:05Z",
        "score": 100,
        "severity": "low",
        "resource_revision": "1",
        "failed_assessment_by_weight": {
          "MINOR": 0
        },
        "assessment_recommendations": {}
      }
    ]
  }

Mengelola profil keamanan

Bagian ini memberikan contoh untuk mengelola profil keamanan menggunakan API dan tidak lengkap. Lihat dokumen referensi securityProfilesV2 API untuk mengetahui informasi selengkapnya.

Mendapatkan profil keamanan kustom yang ada

Perintah ini mengambil informasi untuk semua profil keamanan untuk project Anda:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2" \
      -H "Authorization: Bearer $TOKEN"

Perintah ini mengambil metadata untuk profil keamanan tertentu dan dapat digunakan untuk mengambil informasi tentang profil google-default serta profil kustom:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID" \
      -H "Authorization: Bearer $TOKEN"

Membuat profil keamanan kustom baru

Untuk membuat profil keamanan kustom baru, gunakan perintah seperti ini:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2?security_profile_v2_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H 'Content-type: application/json' \
       -d '{
          "description": "PROFILE_DESC",
          "profile_assessment_configs": {
            "auth-policies-check": {"weight": "MINOR"},
            "threat-policies-check": {"weight": "MODERATE"}
          }
       }'
}

Memperbarui profil keamanan kustom yang ada

Untuk memperbarui profil yang ada, gunakan perintah seperti:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID?update_mask=UPDATE_MASK" \
       -X PATCH \
       -H "Authorization: Bearer $TOKEN" \
       -H 'Content-type: application/json' \
       -d '{"description": "PROFILE_DESC"}'

dengan UPDATE_MASK dapat berupa salah satu nilai berikut, jika ada: description, profile_assessment_configs, description,profile_assessment_configs, atau * (semuanya). Jika menentukan mask update *, permintaan akan memperbarui semua kolom, yang dapat menghapus nilai jika tidak disertakan dalam permintaan.

Menghapus update_mask hanya akan memperbarui kolom yang diberikan dalam permintaan pembaruan.

Menghapus profil keamanan kustom

Menghapus profil keamanan kustom:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/securityProfilesV2/PROFILE_ID" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN"

Penilaian Risiko v1

Bagian ini menampilkan informasi dan contoh untuk API Penilaian Risiko v1.

Batasan pada skor keamanan saat menggunakan API

Skor keamanan memiliki batasan berikut saat digunakan dari API skor keamanan dan profil:

Kolom input yang didukung dalam JSON:
- timeRange: Nilai dibatasi oleh kriteria yang dijelaskan dalam referensi computEnvironmentScores API.
- filters: Lihat Filter yang didukung di API.
- pageSize: Jumlah maksimum subkomponen yang akan ditampilkan dalam satu halaman: 100.
Beberapa filter input tidak didukung.
Kolom dampak dalam respons tidak didukung. (Bidang Dampak adalah potensi dampak rekomendasi ini terhadap skor keseluruhan. Ini menunjukkan seberapa penting rekomendasi ini untuk meningkatkan skor.)

Untuk batasan skor keamanan umum yang tidak khusus digunakan dari API, lihat Batasan skor keamanan v1.

Parameter dalam contoh panggilan API

Bagian berikut memberikan contoh panggilan API dan dapat menggunakan parameter berikut:

ORG adalah organisasi Anda.
ENV adalah lingkungan tempat Anda ingin skor dihitung.
ENVGROUP adalah grup lingkungan yang berisi lingkungan.
PROFILE_ID adalah nama profil. PROFILE_ID dapat berupa default atau nama profil kustom yang Anda buat.
PROFILE_ID harus berisi 1 hingga 63 karakter, yang dapat berupa huruf kecil, angka 0-9, atau tanda hubung. Karakter pertama harus berupa huruf kecil. Karakter terakhir harus berupa huruf kecil atau angka.
PROXY_NAME: Nama proxy.
RESOURCES dapat berupa:
- {"all_resources":true} untuk semua resource dalam cakupan.
- {"includes": { "resources": [{"name": "<proxy-name>"}]} untuk memantau satu atau beberapa proxy yang ditentukan. Misalnya, {"includes": { "resources": [{"name": "my-proxy-1"}]} untuk memantau proxy yang disebut my-proxy-1.
- {"excludes": { "resources": [{"name": "<proxy-name>"}]} untuk memantau semua resource kecuali satu atau beberapa proxy yang ditentukan. Misalnya, {"excludes": { "resources": [{"name": "my-proxy-1"}]} memantau semua resource kecuali proxy yang disebut my-proxy-1.
$TOKEN adalah variabel lingkungan untuk token akses OAuth.
timeRange adalah rentang waktu untuk skor.

Contoh API Penilaian Risiko v1

Filter yang didukung di API

Tabel berikut mencantumkan filter yang didukung di API, dan jalur komponennya.

Filter	Jalur komponen
Skor lingkungan	`/org@ORG/envgroup@ENVGROUP/env@ENV`
Sumber memberi skor semua komponen yang mendasarinya	`/org@ORG/envgroup@ENVGROUP/env@ENV/source`
Skor penyalahgunaan	`/org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse`
Skor untuk semua proxy	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies`
Skor untuk proxy tertentu	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME`
Skor kebijakan untuk proxy tertentu	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual`
Skor kebijakan mediasi untuk proxy tertentu	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/mediation`
Skor kebijakan keamanan untuk proxy tertentu	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security`
Skor kebijakan autentikasi untuk proxy tertentu	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/auth`
Skor kebijakan CORS untuk proxy tertentu	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors`
Skor kebijakan ancaman untuk proxy tertentu	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/threat`
Skor kebijakan untuk semua proxy di lingkungan	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual`
Skor kebijakan mediasi untuk semua proxy di lingkungan	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/mediation`
Skor kebijakan keamanan untuk semua proxy di lingkungan	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security`
Skor kebijakan autentikasi untuk semua proxy di lingkungan	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/auth`
Skor kebijakan CORS untuk semua proxy di lingkungan	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors`
Skor kebijakan ancaman untuk semua proxy di lingkungan	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat`

Menggunakan profil keamanan default

Contoh berikut menunjukkan cara menggunakan profil keamanan default. Lihat Parameter dalam contoh panggilan API untuk parameter yang digunakan dalam contoh.

Melampirkan profil keamanan default ke lingkungan

Untuk melihat skor keamanan, Anda harus melampirkan profil ke lingkungan yang keamanannya ingin Anda evaluasi. Untuk melampirkan profil keamanan default ke lingkungan, gunakan perintah berikut:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments" \
       -X POST \
       -d '{"name": "ENV"}' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Catatan: Parameter securityProfileRevisionId tidak digunakan lagi. Jika Anda menyertakan parameter ini dalam panggilan API, Advanced API Security akan menggunakan revisi terbaru profil, terlepas dari nilai parameter.

Mendapatkan definisi profil keamanan default

Untuk mendapatkan definisi profil keamanan default, masukkan perintah berikut:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default" \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Melepaskan profil keamanan default dari lingkungan

Jika perlu melepaskan profil default dari lingkungan, Anda dapat melakukannya sebagai berikut:

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments/ENV" \
         -X DELETE
         -H 'Content-type: application/json' \
         -H "Authorization: Bearer $TOKEN"

Menggunakan profil keamanan kustom

Anda dapat membuat profil keamanan kustom dengan panggilan API dengan salah satu cara berikut:

Tentukan profil secara eksplisit dalam isi panggilan.
Lampirkan file JSON yang berisi definisi profil ke panggilan.

Bagian berikut memberikan contoh kedua metode tersebut. Lihat Parameter dalam contoh panggilan API untuk parameter yang digunakan dalam contoh.

Kolom berikut dalam contoh panggilan API menentukan profil kustom:

description: Deskripsi profil kustom.
profileConfig: Daftar kategori yang akan disertakan dalam profil kustom. Ini dapat berupa subset dari kategori keamanan berikut:
- abuse
- authorization
- cors
- mtls
- mediation
- threat

Menentukan profil dalam isi panggilan API

Untuk menentukan profil kustom dalam isi panggilan API, masukkan perintah yang mirip dengan berikut ini:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles?security_profile_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
         "description":"test custom profile",
         "profileConfig" : {
           "categories":[
             {"cors":{}},
             {"threat":{}}
           ]
         }
       }'

Tindakan ini akan membuat profil kustom yang menyertakan kategori cors dan threat, dan menampilkan respons seperti ini:

{
  "name": "PROFILE_ID",
  "revisionId": "1",
  "revisionCreateTime": "2023-07-17T18:47:08Z",
  "revisionUpdateTime": "2023-07-17T18:47:08Z",
  "scoringConfigs": [
    {
      "title": "json",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat/json",
      "description": "Check if JSONThreatProtection policy is configured."
    },
    {
      "title": "xml",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat/xml",
      "description": "Check if XMLThreatProtection policy is configured."
    },
    {
      "title": "cors",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors",
      "description": "Check if CORS policy is configured."
    }
  ],
  "maxScore": 1200,
  "minScore": 200,
  "profileConfig": {
    "categories": [
      {
        "cors": {}
      },
      {
        "threat": {}
      }
    ]
  },
  "description": "test custom profile"
  }

Menentukan profil dengan melampirkan file JSON ke panggilan API

Anda juga dapat menentukan profil keamanan kustom dengan melampirkan file JSON yang menentukan profil ke panggilan API. Sebagai contoh, buat file JSON berikut terlebih dahulu:

{
  "description": "test custom profile",
  "profileConfig" : {
    "categories":[
      {"cors":{}},
      {"threat" :{}},
    ]
  }
}

Ini menentukan profil dengan kategori cors dan ancaman. Kemudian, Anda dapat membuat profil berdasarkan kategori ini sebagai berikut:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles?security_profile_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d @create_profile.json

dengan create_profile.json adalah nama file JSON yang dijelaskan di atas.

Mendapatkan definisi profil keamanan kustom

Untuk mendapatkan definisi profil keamanan kustom, masukkan perintah yang mirip dengan berikut ini:

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
         -X GET \
         -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json"

Melepas profil keamanan kustom dari lingkungan

Untuk melepaskan profil keamanan kustom dari lingkungan, masukkan perintah yang mirip dengan berikut ini:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"

Menghapus profil keamanan kustom

Untuk menghapus profil keamanan kustom, masukkan perintah yang mirip dengan berikut:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"

Mendapatkan skor untuk lingkungan

Bagian berikut menyajikan contoh cara mendapatkan skor untuk lingkungan. Lihat Parameter dalam contoh panggilan API untuk parameter yang digunakan dalam contoh.

Mendapatkan semua skor untuk lingkungan

Untuk mendapatkan semua skor untuk lingkungan, masukkan perintah yang mirip dengan berikut ini:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              }
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Lihat halaman referensi computeEnvironmentScores untuk mengetahui deskripsi permintaan dan respons.

Mendapatkan skor sumber untuk lingkungan

Untuk mendapatkan skor sumber untuk lingkungan, masukkan perintah yang mirip dengan berikut:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/source"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Mendapatkan skor penyalahgunaan di sumber untuk lingkungan

Untuk mendapatkan skor penyalahgunaan di sumber untuk suatu lingkungan, masukkan perintah yang mirip dengan berikut ini:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Mendapatkan skor untuk semua proxy di lingkungan

Untuk mendapatkan skor semua proxy di lingkungan, masukkan perintah yang mirip dengan berikut:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Mendapatkan skor untuk proxy tertentu di lingkungan

Untuk mendapatkan skor proxy tertentu di lingkungan, masukkan perintah yang mirip dengan berikut ini:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

dengan PROXY adalah proxy yang skornya ingin Anda dapatkan.

Mendapatkan skor untuk target tertentu di lingkungan

Untuk mendapatkan skor target tertentu di lingkungan, masukkan perintah yang mirip dengan berikut ini:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/target@TARGET"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"