ארגנו מחדש את מבנה הניווט במסמכי התיעוד כדי שיתאים ישירות לתהליכי העבודה התפעוליים שלכם. מידע נוסף זמין בהערות הגרסה ובסרטון ההדרכה.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

מאמרי עזרה על Forwarder Management API

שימו לב: הוצאנו את המעביר משימוש. רכיב ההעברה יוצא בהדרגה משימוש בפלטפורמת Google SecOps, ויגיע לסוף חיי המוצר (EOL) בינואר 2027. 1 באפריל 2026: לקוחות חדשים של Google SecOps לא יכולים להשתמש ברכיב המעביר. 1 בינואר 2027: סיום התמיכה ב-Forwarder באופן רשמי. לא יפורסמו תיקונים נוספים, כולל תיקונים לפגיעויות באבטחה. ‫1 באפריל 2027: אי אפשר יותר להטמיע נתונים מרכיב ההעברה. ‫Google ממליצה להשתמש ב-Bindplane for Google SecOps כפתרון העיקרי לאיסוף יומנים. מידע נוסף זמין במאמר בנושא שימוש ב-Bindplane עם Google SecOps.

אתם יכולים להשתמש ב-methods של Google Security Operations Forwarder Management API כדי לבצע את הפעולות הבאות באופן פרוגרמטי:

ליצור ולנהל כתובות להעברת הודעות.
יצירה וניהול של כלי איסוף.
קבלת תוכן הקובץ להגדרת (.conf) ולאימות (_auth.conf) של מעביר נתונים ב-Google SecOps.

העברת נתונים מורכבת מאוסף אחד או יותר. בכל הגדרה של מאסף מצוינים מנגנון ההטמעה (לדוגמה, File,‏ Kafka,‏ PCAP,‏ Splunk או Syslog) וסוג היומן.

בהנחה שהדרישות לחומרה מתקיימות, אפשר להשתמש בהרבה אוספים באותו מעביר כדי להטמיע נתונים ממגוון מנגנונים וסוגי יומנים. לדוגמה, אפשר להתקין מעביר עם שני אוספי syslog שמקשיבים לנתוני PAN_FIREWALL ו-CISCO_ASA_FIREWALL ביציאות נפרדות, בהתאמה.

ה-API מאפשר לכם ליצור מעבירי נתונים ואת האוספים שלהם במופע Google SecOps. אחרי שיוצרים מעביר, אפשר להשתמש בנקודת הקצה Generate Forwarder Files כדי לקבל את תוכן הקובץ (כמטען ייעודי (payload) בפורמט JSON) של קובצי ההגדרה (.conf) והאימות (_auth.conf) של המעביר. אחר כך אפשר לכתוב את התוכן הזה לקובצי .conf המתאימים לצורך פריסה באמצעות שירות Google SecOps Forwarder במערכת Windows או Linux.

דוגמאות ל-Python שמשתמשות ב-Forwarder Management API זמינות במאגר GitHub.

יצירת מעביר ומרכזים לאיסוף נתונים

צריך ליצור מעביר לפני שיוצרים את אחד מהאוספים שלו.

כדי ליצור מעביר ומרכזים לאיסוף נתונים:

יצירת כתובת להעברת הודעות
יוצרים כלי לאיסוף נתונים עבור המעביר.
(אופציונלי) חוזרים על שלב 2 כדי להוסיף עוד כלי איסוף.

קבלת פרטי כניסה לאימות API

נציג Google Security Operations יספק לכם פרטי כניסה של חשבון שירות למפתחים ב-Google כדי לאפשר ללקוח ה-API לתקשר עם ה-API.

בנוסף, צריך לספק את היקף ההרשאה כשמפעילים את לקוח ה-API. ב-OAuth 2.0 נעשה שימוש בהיקף כדי להגביל את הגישה של אפליקציה לחשבון. כשאפליקציה מבקשת היקף הרשאות, טוקן הגישה שמונפק לאפליקציה מוגבל להיקף ההרשאות שאושרו.

כדי לאתחל את לקוח Backstory API, צריך להשתמש בהיקף הבא:

https://www.googleapis.com/auth/chronicle-backstory

דוגמה ל-Python

בדוגמה הבאה ב-Python מוצג שימוש בפרטי כניסה של OAuth2 ובלקוח HTTP באמצעות google.oauth2 ו-googleapiclient.

# Imports required for the sample - Google Auth and API Client Library Imports.
# Get these packages from https://pypi.org/project/google-api-python-client/ or run $ pip
# install google-api-python-client from your terminal
from google.auth.transport import requests
from google.oauth2 import service_account

SCOPES = ['https://www.googleapis.com/auth/chronicle-backstory']

# The apikeys-demo.json file contains the customer's OAuth 2 credentials.
# SERVICE_ACCOUNT_FILE is the full path to the apikeys-demo.json file
# ToDo: Replace this with the full path to your OAuth2 credentials
SERVICE_ACCOUNT_FILE = '/customer-keys/apikeys-demo.json'

# Create a credential using the Google Developer Service Account Credential and Backstory API
# Scope.
credentials = service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, scopes=SCOPES)

# Build a requests Session Object to make authorized OAuth requests.
http_session = requests.AuthorizedSession(credentials)

# Your endpoint GET|POST|PATCH|etc. code will vary below

# Reference List example (for US region)
url = 'https://backstory.googleapis.com/v2/lists/COLDRIVER_SHA256'

# You might need another regional endpoint for your API call; see
# https://cloud.google.com/chronicle/docs/reference/ingestion-api#regional_endpoints

# requests GET example
response = http_session.request("GET", url)

# POST example uses json
body = {
  "foo": "bar"
}
response = http_session.request("POST", url, json=body)

# PATCH example uses params and json
params = {
  "foo": "bar"
}
response = http_session.request("PATCH", url, params=params, json=body)

# For more complete examples, see:
# https://github.com/chronicle/api-samples-python/

מגבלות על שאילתות ב-Backstory API

ה-Backstory API אוכף מגבלות על נפח הבקשות שכל לקוח יכול לשלוח לפלטפורמת Google SecOps. אם מגיעים למגבלת השאילתות או חורגים ממנה, שרת Backstory API מחזיר HTTP 429 (RESOURCE_EXHAUSTED) למתקשר. כשמפתחים אפליקציות ל-Backstory API, ‏ Google ממליצה להגדיר הגבלות קצב במערכת כדי למנוע ניצול יתר של משאבים. המגבלות האלה חלות על כל ממשקי ה-API של Backstory, כולל ממשקי ה-API של Search,‏ Forwarder Management ו-Tooling.

רשימה מפורטת של מכסות Backstory API

המגבלה הבאה נאכפת בניהול המעבירים ונמדדת בשאילתות לשנייה (QPS):

‫Backstory API	נקודת קצה ל-API	מגבלה
ניהול של תוכנת Forwarder	יצירת כתובת להעברת דואר	‫1 QPS
	קבלת תוכנת Forwarder	‫1 QPS
	הצגת רשימה של כתובות להעברה	‫1 QPS
	עדכון כלי ההעברה	‫1 QPS
	מחיקת כתובת להעברת דואר	‫1 QPS
ניהול השרתים לאיסוף נתונים	יצירת כלי לאיסוף מידע	‫1 QPS
	קבלת אספן	‫1 QPS
	רשימת מכשירים לאיסוף נתונים	‫1 QPS
	עדכון של כלי לאיסוף נתונים	‫1 QPS
	מחיקת כלי לאיסוף מידע	‫1 QPS

הפניה לשיטות של Forwarder API

בקטע הזה מוסבר על נקודות הקצה ליצירה ולניהול של כתובות להעברת הודעות. נקודות הקצה ליצירה ולניהול של כלי איסוף מפורטות במאמר Collector API reference.

יצירת כתובת להעברת דואר

יוצר מעביר חדש במכונת Google SecOps. ההפניה החדשה תכלול את כל ערכי ההגדרה של ההפניה שסופקו בגוף הבקשה. צריך לציין את ערכי ההגדרה של המאגדים באמצעות Create Collector אחרי השימוש ב-Create Forwarder.

בהגדרות מסוימות, ערכי ההגדרה שחסרים או שהערך שלהם הוא אפס בגוף הבקשה מוגדרים לערכי ברירת מחדל. פרטים על השדות והערכים של המעביר מופיעים במאמר שדות להגדרת מעביר.

בקשה

POST https://backstory.googleapis.com/v2/forwarders

גוף הבקשה

{
  "display_name": string,
  "config": {
    object (ForwarderConfig)
  }
}

פרמטרים של הגוף

שדה	סוג	חובה	תיאור
display_name	מחרוזת	חובה	השם של המעביר. השם הזה מוצג בממשק של Google SecOps.
config	object	אופציונלי	הגדרות התצורה של המעביר הזה. שדות להגדרת מעביר

דוגמה לבקשה

בדוגמה הזו מוצגים צמדי המפתח:ערך שנדרשים בבקשה ליצירת מעביר. אם לא מציינים שדה בבקשה ויש לו ערך ברירת מחדל, המערכת משתמשת בערך ברירת המחדל במהלך יצירת המעביר. פרטים על ערכי ברירת המחדל מופיעים במאמר שדות ההגדרות של המעביר.

POST https://backstory.googleapis.com/v2/forwarders
{
  "display_name": "chronicle_forwarder"
}

תשובה

אם הבקשה מצליחה, התשובה מחזירה קוד סטטוס של HTTP‏ 200 (OK).

בתגובה מוצגים ערכי ההגדרה שהוחלו במהלך היצירה של המעביר. ערכי ברירת המחדל של ההגדרות מסוימות מוחלים במהלך יצירת משאבים אם השדות האלה חסרים או שהערך שלהם הוא אפס בגוף הבקשה. פרטים נוספים מופיעים במאמר בנושא שדות של הגדרות העברה.

שדות תשובה

בנוסף לשדות שצוינו בבקשה ולשדות שמוחלים עליהם ערכי ברירת מחדל, התגובה כוללת את השדות הבאים שנוצרו ושמיועדים לפלט בלבד.

שדה	סוג	תיאור
name	מחרוזת	מזהה המשאב של חברת השילוח. הפורמט הוא ‎"forwarders/forwarderID"‎. לדוגמה: forwarders/12ab3cd4-56ef-7ghi-j89k-1l23m4nopq56
הסמוי הסופי	enum	מציין את המצב הנוכחי של המעביר. הערכים החוקיים הם: פעיל: למעביר מותר להעלות נתונים. מושעה: אין לאפליקציה הרשאה להעלאת נתונים. ערך ברירת המחדל הוא ACTIVE.

שדה

סוג

תיאור

name

מחרוזת

מזהה המשאב של חברת השילוח. הפורמט הוא ‎"forwarders/forwarderID"‎. לדוגמה:

forwarders/12ab3cd4-56ef-7ghi-j89k-1l23m4nopq56

הסמוי הסופי

enum

מציין את המצב הנוכחי של המעביר. הערכים החוקיים הם:

פעיל: למעביר מותר להעלות נתונים.
מושעה: אין לאפליקציה הרשאה להעלאת נתונים.

ערך ברירת המחדל הוא ACTIVE.

דוגמה לתגובה

זוהי דוגמה לתשובה שמוחזרת לבקשת הדוגמה שלמעלה.

{
  "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56",
  "displayName": "chronicle_forwarder",
  "config": {
    "uploadCompression": "false",
    "serverSettings": {
      "gracefulTimeout": 15,
      "drainTimeout": 10,
      "httpSettings": {
        "port": "8080",
        "host": "0.0.0.0",
        "readTimeout": "3",
        "readHeaderTimeout": "3",
        "writeTimeout": "3",
        "idleTimeout": "3"
        "routeSettings": {
          "availableStatusCode": "204",
          "readyStatusCode": "204",
          "unreadyStatusCode": "503"
        },
      },
    },
  },
  "state": "ACTIVE"
}

קבלת תוכנת Forwarder

מחזירה כתובת להעברת אימייל.

בקשה

GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}

גוף הבקשה

אל תכללו גוף בקשה.

דוגמה לבקשה

GET https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56

דוגמה לתגובה

{
  "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56",
  "displayName": "chronicle_forwarder",
  "config": {
    "uploadCompression": "false",
    "serverSettings": {
      "gracefulTimeout": 15,
      "drainTimeout": 10,
      "httpSettings": {
        "port": "8080",
        "host": "0.0.0.0",
        "readTimeout": "3",
        "readHeaderTimeout": "3",
        "writeTimeout": "3",
        "idleTimeout": "3"
        "routeSettings": {
          "availableStatusCode": "204",
          "readyStatusCode": "204",
          "unreadyStatusCode": "503"
        },
      },
    },
  },
  "state": "ACTIVE"
}

הצגת רשימה של כתובות להעברה

מציגה את כל המעבירים של מכונת Google SecOps.

בקשה

GET https://backstory.googleapis.com/v2/forwarders

דוגמה לבקשה

GET https://backstory.googleapis.com/v2/forwarders

תשובה

מחזירה רשימה של כתובות להעברה.

דוגמה לתגובה

{
  "forwarders": [
    {
      "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56",
      "displayName": "chronicle_forwarder_1",
      "config": {
        "uploadCompression": "false",
        "serverSettings": {
          "gracefulTimeout": 15,
          ...
         },
      },
      "state": "ACTIVE"
    },
    {
      "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde57",
      "displayName": "chronicle_forwarder_2",
      "config": {
        "uploadCompression": "false",
        "serverSettings": {
          "gracefulTimeout": 15,
       ...
       },
      },
      "state": "ACTIVE"
    }
  ]
}

עדכון כלי ההעברה

אפשר לעדכן מפנה באמצעות פרמטר השאילתה של כתובת ה-URL ‏updateMask כדי לציין את השדות לעדכון.

לדוגמה, כדי לעדכן את השם המוצג, משתמשים בפרמטר השאילתה updateMask בבקשת התיקון באופן הבא:

?updateMask=displayName

גוף הבקשה צריך לכלול רק את השדות שרוצים לעדכן (במיקומים המדויקים שלהם).

בקשה

PATCH https://backstory.googleapis.com/v2/forwarders/{forwarderID}?updateMask=<field_1,field_2>

גוף הבקשה

{
  "display_name": string,
  "config": {
    object (ForwarderConfig)
  },
}

פרמטרים של הגוף

שדה	סוג	חובה	תיאור
display_name	מחרוזת	חובה	השם של המעביר. השם הזה מוצג בממשק של Google SecOps.
config	object	אופציונלי	הגדרות התצורה של המעביר הזה. שדות להגדרת מעביר

דוגמה לבקשה

זו דוגמה לבקשה לעדכון מעביר, שבה הבקשה מציינת ערכים חדשים ל-displayName ומוסיפה תווית מטא-נתונים.

PATCH https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56?updateMask=displayName,config.metadata.labels
{
  "display_name": "UpdatedForwarder",
  "config": {
    "metadata": {
      "labels": [
        {
          "key": "office",
          "value": "corporate",
        }
      ]
    }
  }
}

דוגמה לתגובה

זוהי דוגמה לתשובה שמוחזרת לבקשת הדוגמה שלמעלה.

{
  "name": "forwarders/{forwarderUUID}",
  "displayName": "UpdatedForwarder",
  "config": {
    "uploadCompression": "false",
    "metadata": {
      "labels": [
        {
          "key": "office",
          "value": "corporate"
        }
      ]
    }
  },
  "state": "ACTIVE"
}

מחיקת כתובת להעברת דואר

מוחקת את המעביר.

בקשה

DELETE https://backstory.googleapis.com/v2/forwarders/{forwarderID}

גוף הבקשה

אל תכללו גוף בקשה.

דוגמה לבקשה

DELETE https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56

דוגמה לתגובה

אם הפעולה מצליחה, הפונקציה Delete Forwarder מחזירה תגובה ריקה עם קוד סטטוס של HTTP‏ 200 (OK).

{}

יצירת קובצי העברה

הפעולה יוצרת ומחזירה את התוכן של קובצי התצורה (.conf) והאימות (_auth.conf) של המעביר.

בקשה

GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}:generateForwarderFiles

גוף הבקשה

אל תכללו גוף בקשה.

דוגמה לבקשה

GET https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56:generateForwarderFiles

דוגמה לתגובה

אם הפעולה בוצעה ללא שגיאות, היא מחזירה קוד סטטוס של HTTP 200 (OK). הוא גם מחזיר את התוכן של קובץ ההגדרות של המעביר, כולל נתוני ההגדרות של האוספים של המעביר, וגם את התוכן של קובץ האימות (_auth.conf) שמשמש את המעביר לאימות עם מופע Google SecOps.

שדות להגדרת התצורה של המעביר

בטבלה הבאה מפורטות הגדרות התצורה של המעביר שאפשר לציין באמצעות Create Forwarder ו-Update Forwarder. אם לא מציינים ערך להגדרה כשמשתמשים באפשרות'יצירת מעביר', מוחל ערך ברירת המחדל של ההגדרה (שמוצג בהמשך).

אפשר לציין את השדות הבאים באובייקט config של גוף הבקשה.

שדה	סוג	חובה	תיאור
upload_compression	bool	אופציונלי	אם `true`, קבוצות של נתונים נדחסות לפני ההעלאה. ערך ברירת המחדל הוא `false`.
metadata.asset_namespace	מחרוזת	אופציונלי	מרחב השמות לזיהוי יומנים מהמעביר הזה. הערה: זו הגדרה גלובלית שחלה על המעביר ועל האוספים של המעביר, אלא אם היא מוחלפת ברמת האוסף. מידע נוסף זמין במאמר הגדרת מרחבי שמות.
metadata.labels	list	אופציונלי	רשימה של צמדי מפתח:ערך שרירותיים שאפשר לציין בהגדרות של המעביר. הערה: זו הגדרה גלובלית שחלה על המעביר ועל האוספים של המעביר, אלא אם היא מוחלפת ברמת האוסף.
metadata.labels.key	מחרוזת	אופציונלי	המפתח של שדה ברשימת תוויות המטא-נתונים.
metadata.labels.value	מחרוזת	אופציונלי	הערך של שדה ברשימת תוויות המטא-נתונים.
regex_filters.description	מחרוזת	אופציונלי	תיאור של מה מסונן ולמה.
regex_filters.regexp	מחרוזת	אופציונלי	הביטוי הרגולרי שמשמש להתאמה לכל שורה נכנסת.
regex_filters.behavior	enum	אופציונלי	מציין את מצב הפונקציונליות של השרת. הערכים האפשריים הם: ALLOW: המצב הזה מאפשר להעלות את השורה המסוננת. חסימה: המצב הזה מונע את העלאת השורה המסוננת.
server_settings	object	אופציונלי	הגדרות שמגדירות את שרת ה-HTTP המובנה של המעביר, שאפשר להשתמש בו כדי להגדיר אפשרויות של איזון עומסים וזמינות גבוהה לאיסוף של syslog ב-Linux.
server_settings.state	enum	אופציונלי	מציין את מצב הפונקציונליות של השרת. הערכים האפשריים הם: פעיל: במצב הזה, הגדרות השרת מוחלות כמו שצוין. מושהה במצב הזה, הגדרות השרת לא מוחלות.
server_settings.graceful_timeout	integer	אופציונלי	מספר השניות שאחריהן המעביר מחזיר בדיקת מוכנות או תקינות שגויה, ועדיין מקבל חיבורים חדשים. זה גם הזמן להמתנה בין קבלת אות להפסקה לבין התחלת הכיבוי של השרת עצמו. כך מאזן העומסים יכול להסיר את המעביר מהמאגר. ערך ברירת המחדל הוא `15`.
server_settings.drain_timeout	integer	אופציונלי	מספר השניות שהמעביר ממתין עד שחיבורים פעילים ייסגרו בעצמם בהצלחה, לפני שהשרת סוגר אותם. ערך ברירת המחדל הוא `10`.
server_settings.http_settings.port	integer	אופציונלי	מספר היציאה שהשרת HTTP מאזין לה לבדיקות תקינות ממאזן העומסים. הערך חייב להיות בין 1024 ל-65535. ערך ברירת המחדל הוא `8080`.
server_settings.http_settings.host	מחרוזת	אופציונלי	כתובת ה-IP או שם המארח שאפשר לזהות ככתובות IP, שהשרת צריך להאזין להן. ערך ברירת המחדל הוא `0.0.0.0` (המערכת המקומית).
server_settings.http_settings.read_timeout	integer	אופציונלי	מספר השניות המקסימלי שמוקצב לקריאת בקשות שלמות, כולל הכותרת והגוף. ערך ברירת המחדל הוא `3`.
server_settings.http_settings.read_header_timeout	integer	אופציונלי	מספר השניות המקסימלי שמוקצב לקריאת כותרות של בקשות. ערך ברירת המחדל הוא `3`.
server_settings.http_settings.write_timeout	integer	אופציונלי	מספר השניות המקסימלי שמוקצב לשליחת תגובה. ערך ברירת המחדל הוא `3`.
server_settings.http_settings.idle_timeout	integer	אופציונלי	מספר השניות המקסימלי להמתנה לבקשה הבאה כשחיבורים בלי פעילות מופעלים. ערך ברירת המחדל הוא `3`.
server_settings.http_settings.route_settings.available_status_code	integer	אופציונלי	קוד הסטטוס שמוחזר כשמתקבלת בדיקת פעילות והמפנה זמין. ערך ברירת המחדל הוא `204`.
server_settings.http_settings.route_settings.ready_status_code	integer	אופציונלי	קוד המצב שמוחזר כשהמפנה מוכן לקבל תנועה. ערך ברירת המחדל הוא `204`.
server_settings.http_settings.route_settings.unready_status_code	integer	אופציונלי	קוד הסטטוס שמוחזר כשמפנה התנועה לא מוכן לקבל תנועה. ערך ברירת המחדל הוא `503`.

הפניה לשיטות של Collector API

בקטע הזה מתוארות נקודות הקצה (endpoints) לעבודה עם כלי איסוף.

כשיוצרים ומעדכנים אוספים, חשוב לזכור שכל הגדרה של אוסף יכולה לציין הגדרות של קליטת נתונים לאחד מהמקורות הבאים, אבל לא ליותר מאחד:

נתונים בקובץ יומן
נושאים ב-Kafka
נתוני חבילות (pcap)
נתוני Splunk
נתוני Syslog

לנקודות קצה לעבודה עם מעבירי דואר, אפשר לעיין בהפניית API של מעבירי דואר.

יצירת כלי לאיסוף מידע

יוצר אספן חדש בחשבון Google SecOps. צריך לציין ערכי תצורה של אוספים באמצעות Create Collector אחרי שמשתמשים ב-Create Forwarder.

הגדרות מסוימות, שערכי התצורה שלהן חסרים או שהערך שלהן הוא אפס בגוף הבקשה, מוגדרות לערכי ברירת מחדל. פרטים על השדות והערכים של הגדרות כלי האיסוף זמינים במאמר שדות של הגדרות כלי האיסוף.

בקשה

POST https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors

גוף הבקשה

{
  "display_name": string,
  "config": {
    object (CollectorConfig)
  }
  "state": enum
}

פרמטרים של הגוף

שדה	סוג	חובה	תיאור
display_name	מחרוזת	חובה	השם של כלי האיסוף. השם הזה מוצג בממשק של Google SecOps.
config	object	חובה	הגדרות התצורה של האוסף הזה. מידע נוסף מופיע במאמר בנושא שדות להגדרת כלי האיסוף.
הסמוי הסופי	enum	אופציונלי	מציין את המצב הנוכחי של הכלי לאיסוף נתונים. הערכים החוקיים הם: פעיל: המערכת מאפשרת לאמצעי האיסוף לקבל נתונים. הושעה: לא ניתן לאסוף נתונים.

שדה

סוג

חובה

תיאור

display_name

מחרוזת

חובה

השם של כלי האיסוף. השם הזה מוצג בממשק של Google SecOps.

config

object

חובה

הגדרות התצורה של האוסף הזה. מידע נוסף מופיע במאמר בנושא שדות להגדרת כלי האיסוף.

הסמוי הסופי

enum

אופציונלי

מציין את המצב הנוכחי של הכלי לאיסוף נתונים. הערכים החוקיים הם:

פעיל: המערכת מאפשרת לאמצעי האיסוף לקבל נתונים.
הושעה: לא ניתן לאסוף נתונים.

דוגמה לבקשה

בדוגמה הזו מוצגים צמדי המפתח:ערך הנדרשים בבקשה ליצירת אוסף. לכל השדות שלא סופקו, ערכי ברירת מחדל מוחלים במהלך יצירת כלי האיסוף.

בדוגמה הזו, סוג ה-Collector הוא file, ולכן הגדרת ה-Collector כוללת את file_settings כדי לציין את סוג ה-Collector וההגדרות שלו. אם סוג האוסף הוא syslog, ההגדרה של האוסף כוללת syslog_settings. מידע נוסף זמין במאמר בנושא שדות להגדרת כלי האיסוף.

POST https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors
{
  "display_name": "abc_collector",
  "config" {
    "log_type": "CS_EDR"
    "file_settings": {
      "file_path": "/opt/chronicle/edr/output/sample.txt",
    }
  }
}

תשובה

אם הבקשה מצליחה, התשובה מחזירה קוד סטטוס של HTTP‏ 200 (OK).

בתגובה מוצגים ערכי ההגדרה שהוחלו במהלך היצירה של האוסף. ערכי ברירת המחדל של ההגדרות מסוימות מוחלים במהלך יצירת משאבים אם השדות האלה חסרים או שהערך שלהם הוא אפס בגוף הבקשה. פרטים נוספים מופיעים במאמר שדות להגדרת כלי האיסוף.

שדות תשובה

בנוסף לשדות שצוינו בבקשה ולשדות שמוחלים עליהם ערכי ברירת מחדל, התשובה כוללת את השדות הבאים:

שדה	סוג	תיאור
name	מחרוזת	מזהה המשאב של כלי האיסוף. הפורמט הוא ‎"forwarders/{forwarderID}/collectors/{collectorID}"‎. לדוגמה: `forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56`

דוגמה לתגובה

זוהי דוגמה לתשובה שמוחזרת לבקשת הדוגמה שלמעלה.

{
  "name": "forwarders/12ab3cd4-56ef-7ghi-j89k-1l23m4nopq56/collectors/
     98ab7cd6-54ef-3abc-d21e-1f23a4bcde56",
  "displayName": "abc_collector",
  "config": {
    "logType": "tomcat",
    "maxSecondsPerBatch": "10",
    "maxBytesPerBatch": "1048576"
  }
}

קבלת אספן

מחזירה אובייקט Collector.

בקשה

‫

GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors/{collectorID}

גוף הבקשה

אל תכללו גוף בקשה.

דוגמה לבקשה

GET
https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56

דוגמה לתגובה

{
  "name": "?",
  "displayName": "abc_collector",
  "config": {
    "logType": "tomcat",
    "maxSecondsPerBatch": "10",
    "maxBytesPerBatch": "1048576"
  }
}

רשימת מכשירים לאיסוף נתונים

רשימה של האוספים הקיימים עבור המעביר שצוין.

בקשה

GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors

דוגמה לבקשה

GET https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors

תשובה

מחזירה כמה אוספים.

דוגמה לתגובה

{
  "collectors": [
    {
      "name": "?",
      "displayName": "abc_collector_1",
      "config": {
        "logType": "tomcat",
        "maxSecondsPerBatch": "10",
        "maxBytesPerBatch": "1048576"
      }
    },
    {
      "name": "?",
      "displayName": "abc_collector_2",
      "config": {
        "logType": "tomcat",
        "maxSecondsPerBatch": "10",
        "maxBytesPerBatch": "1048576"
      }
    }
  ]
}

עדכון של כלי לאיסוף נתונים

כשמעדכנים מאסף באמצעות ה-API, אפשר לבחור להחליף את כל ההגדרות של המאסף או להחליף רק שדות ספציפיים בהגדרות שלו. בדרך כלל עדיף להחליף שדות ספציפיים, כדי להימנע מהחלפה של כל הנתונים בטעות. כדי להחליף שדות ספציפיים, צריך לספק FieldMask לבקשת העדכון.

כדי לספק FieldMask לעדכון השם המוצג של כלי לאיסוף נתונים, צריך לספק את פרמטר השאילתה של כתובת ה-URL updateMask בבקשת התיקון. לדוגמה:

?updateMask=displayName

גוף הבקשה צריך לכלול רק את השדות שרוצים לעדכן (במיקומים המדויקים שלהם).

בקשה

PATCH https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors/{collectorID}?updateMask=<field_1,field_2>

גוף הבקשה

{
  "display_name": string,
  "config": {
    object (CollectorConfig)
  },
}

פרמטרים של הגוף

שדה	סוג	חובה	תיאור
displayName	מחרוזת	חובה	השם של כלי האיסוף. השם הזה מוצג בממשק של Google SecOps.
config	object	אופציונלי	הגדרות התצורה של המעביר הזה. מידע נוסף מופיע במאמר בנושא שדות להגדרת כלי האיסוף.

דוגמה לבקשה

זו דוגמה לבקשת Update Collector שבה מצוינים ערכים חדשים ל-displayName, ל-logType, ל-assetNamespace ול-protocol.

PATCH https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56?updateMask=displayName,config.logType,config.metadata.assetNamespace,config.syslogSettings.protocol
{
  "display_name": "UpdatedCollector"
  "config": {
    "metadata": {
      "asset_namespace": "COLLECTOR",
      },
      "log_type": "CISCO_ASA_FIREWALL",
      "syslog_settings": {
        "protocol": "TCP",
      }
    }
  }

דוגמה לתגובה

זוהי דוגמה לתשובה שמוחזרת לבקשת הדוגמה שלמעלה.

{
  "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56",
  "displayName": "UpdatedCollector",
  "config": {
    "logType": "CISCO_ASA_FIREWALL",
    "metadata": {
      "assetNamespace": "COLLECTOR"
    },
    "maxSecondsPerBatch": 10,
    "maxBytesPerBatch": "1048576",
    "syslogSettings": {
      "protocol": "TCP",
      "address": "0.0.0.0",
      "port": 10514,
    }
  },
  "state": "ACTIVE"
}

מחיקת כלי לאיסוף מידע

מחיקת כלי לאיסוף נתונים.

בקשה

DELETE https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors/{collectorID}

גוף הבקשה

אל תכללו גוף בקשה.

דוגמה לבקשה

DELETE https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56

דוגמה לתגובה

אם הפעולה מצליחה, הכלי למחיקת נתונים חוזר עם תגובה ריקה עם קוד סטטוס של HTTP‏ 200 (OK).

{}

שדות להגדרת האוסף

אפשר לציין את השדות הבאים באובייקט config של גוף הבקשה.

שדה	סוג	חובה	תיאור
log_type	מחרוזת	חובה	סוג יומן נתמך (שאפשר להעביר ל-Google SecOps). רשימה של סוגי יומנים נתמכים שלגביהם יש ל-Google SecOps מנתח מופיעה בעמודה Ingestion Label (תווית ההטמעה) בדף Supported default parsers (מנתחים נתמכים שמוגדרים כברירת מחדל). כדי לראות את הרשימה המלאה של סוגי היומנים הנתמכים, משתמשים בנקודת הקצה `logtypes`.
metadata.asset_namespace	object	אופציונלי	מרחב השמות לזיהוי יומנים מהכלי הזה לאיסוף נתונים. הערה: זו הגדרה גלובלית שחלה על המעביר ועל האוספים של המעביר, אלא אם היא מוחלפת ברמת האוסף. מידע נוסף זמין במאמר הגדרת מרחבי שמות.
metadata.labels	list	אופציונלי	רשימה של צמדי מפתח:ערך שרירותיים שאפשר לציין בהגדרות של כלי האיסוף. הערה: זו הגדרה גלובלית שחלה על המעביר ועל האוספים של המעביר, אלא אם היא מוחלפת ברמת האוסף.
metadata.labels.key	מחרוזת	אופציונלי	המפתח של שדה ברשימת תוויות המטא-נתונים.
metadata.labels.value	מחרוזת	אופציונלי	הערך של שדה ברשימת תוויות המטא-נתונים.
regex_filters.description	מחרוזת	אופציונלי	תיאור של מה מסונן ולמה.
regex_filters.regexp	מחרוזת	אופציונלי	הביטוי הרגולרי שמשמש להתאמה לכל שורה נכנסת.
regex_filters.behavior	enum	אופציונלי	מציין את מצב הפונקציונליות של השרת. הערכים האפשריים הם: ALLOW: המצב הזה מאפשר להעלות את השורה המסוננת. חסימה: המצב הזה מונע את העלאת השורה המסוננת.
disk_buffer.state	enum	אופציונלי	מציין את מצב החיץ בדיסק של האוסף. הערכים החוקיים הם: ACTIVE: האגירה מופעלת. SUSPENDED: השימוש במאגר נתונים זמני מושבת.
disk_buffer.directory_path	מחרוזת	אופציונלי	נתיב הספרייה לקבצים שנכתבו.
disk_buffer.max_file_buffer_bytes	integer	אופציונלי	גודל הקובץ המקסימלי שניתן לשמור בזיכרון.
max_seconds_per_batch	integer	אופציונלי	מספר השניות בין קבוצות. ערך ברירת המחדל הוא `10`.
max_bytes_per_batch	integer	אופציונלי	מספר הבייטים שנוספו לתור לפני העלאת קבוצת הפריטים של המעביר. ערך ברירת המחדל הוא `1048576`.
‪<collector_type>_settings.<fields>		חובה	מציין סוג של כלי לאיסוף נתונים וההגדרות שלו. כל כלי איסוף צריך לציין סוג אחד של כלי איסוף ואת השדות שלו. לדוגמה, כדי להשתמש בסוג `file` collector, צריך להוסיף את השדה `file_settings.file_path` להגדרה ולתת לו ערך. לדוגמה: `"file_settings": { "file_path": "/opt/chronicle/edr/output/sample.txt", }` סוגי הנתונים והשדות שלהם מפורטים בשורות הבאות בטבלה הזו. סוגי האוספים הזמינים הם: `file` `kafka` `pcap` `splunk` `syslog`
file_settings.file_path	מחרוזת	אופציונלי	הנתיב של הקובץ למעקב.
kafka_settings.authentication.username	מחרוזת	אופציונלי	שם המשתמש של הזהות שמשמשת לאימות.
kafka_settings.authentication.password	מחרוזת	אופציונלי	הסיסמה של החשבון שזוהה על ידי שם המשתמש.
kafka_settings.topic	מחרוזת	אופציונלי	נושא Kafka שממנו מתבצעת ההטמעה של הנתונים. פרטים נוספים זמינים במאמר בנושא איסוף נתונים מנושאי Kafka.
kafka_settings.group_id	מחרוזת	אופציונלי	מזהה קבוצה.
kafka_settings.timeout	integer	אופציונלי	מספר השניות המקסימלי שחיוג ימתין עד להשלמת החיבור. ערך ברירת המחדל הוא `60`.
kafka_settings.brokers	מחרוזת	אופציונלי	מחרוזת חוזרת שמפרטת את ברוקרי Kafka. לדוגמה: ‎"broker-1:9092", "broker-2:9093" הערה: כל הערכים מוחלפים במהלך פעולת עדכון. לכן, כדי לעדכן רשימה של ברוקרים ולהוסיף ברוקר חדש, צריך לציין את כל הברוקרים הקיימים ואת הברוקר החדש.
kafka_settings.tls_settings.certificate	מחרוזת	אופציונלי	הנתיב ושם הקובץ של האישור. לדוגמה: `/path/to/cert.pem`
kafka_settings.tls_settings.certificate_key	מחרוזת	אופציונלי	הנתיב ושם הקובץ של מפתח האישור. לדוגמה: `/path/to/cert.key`
kafka_settings.tls_settings.minimum_tls_version	מחרוזת	אופציונלי	גרסת ה-TLS המינימלית.
kafka_settings.tls_settings.insecure_skip_verify	bool	אופציונלי	אם `true`, מופעל אימות של אישור SSL. ערך ברירת המחדל הוא `false`.
pcap_settings.network_interface	מחרוזת	אופציונלי	הממשק להאזנה לנתוני PCAP.
pcap_settings.bpf	מחרוזת	אופציונלי	‫Berkeley Packet Filter‏ (BPF) עבור pcap.
splunk_settings.authentication.username	מחרוזת	אופציונלי	שם המשתמש של הזהות שמשמשת לאימות.
splunk_settings.authentication.password	מחרוזת	אופציונלי	הסיסמה של החשבון שזוהה על ידי שם המשתמש.
splunk_settings.host	מחרוזת	אופציונלי	המארח או כתובת ה-IP של Splunk API בארכיטקטורת REST.
splunk_settings.port	integer	אופציונלי	היציאה של Splunk API בארכיטקטורת REST.
splunk_settings.minimum_window_size	integer	אופציונלי	טווח הזמן המינימלי בשניות לחיפוש נתון ב-Splunk. פרטים נוספים זמינים במאמר בנושא איסוף נתונים מ-Splunk. ערך ברירת המחדל הוא `10`.
splunk_settings.maximum_window_size	integer	אופציונלי	טווח הזמן המקסימלי בשניות לחיפוש נתון ב-Splunk. פרטים נוספים זמינים במאמר בנושא איסוף נתונים מ-Splunk. ערך ברירת המחדל הוא `30`.
splunk_settings.query_string	מחרוזת	אופציונלי	השאילתה שמשמשת לסינון רשומות ב-Splunk. לדוגמה: `search index=* sourcetype=dns`
splunk_settings.query_mode	מחרוזת	אופציונלי	מצב השאילתה של Splunk. לדוגמה: `realtime`
splunk_settings.cert_ignored	bool	אופציונלי	אם הערך הוא `true`, המערכת מתעלמת מהאישור.
syslog_settings.protocol	enum	אופציונלי	מציין את הפרוטוקול שבו הכלי לאיסוף נתונים ישתמש כדי להאזין לנתוני syslog. הערכים החוקיים הם: `TCP` `UDP`
syslog_settings.address	מחרוזת	אופציונלי	כתובת ה-IP או שם המארח של המיקום שבו נמצא הכלי לאיסוף נתונים, והוא מאזין לנתוני syslog.
syslog_settings.port	integer	אופציונלי	יציאת היעד שבה נמצא האוסף והוא מקשיב לנתוני syslog.
syslog_settings.buffer_size	integer	אופציונלי	הגודל בבייטים של המאגר של שקע ה-TCP.‫ ערך ברירת המחדל של TCP הוא `65536`.‫ ברירת המחדל של UDP היא `8192`.
syslog_settings.connecton_timeout	integer	אופציונלי	מספר השניות של חוסר פעילות שאחריהן חיבור ה-TCP מנותק. ערך ברירת המחדל הוא `60`.
syslog_settings.tls_settings.certificate	מחרוזת	אופציונלי	הנתיב ושם הקובץ של האישור. לדוגמה: `/path/to/cert.pem`
syslog_settings.tls_settings.certificate_key	מחרוזת	אופציונלי	הנתיב ושם הקובץ של מפתח האישור. לדוגמה: `/path/to/cert.key`
syslog_settings.tls_settings.minimum_tls_version	מחרוזת	אופציונלי	גרסת ה-TLS המינימלית.
syslog_settings.tls_settings.insecure_skip_verify	bool	אופציונלי	אם `true`, מופעל אימות של אישור SSL. ערך ברירת המחדל הוא `false`.