Функции разбора

В данной статье при описании функций приняты следующие обозначения:

  • Типы значений, которые принимает аргумент, указаны в угловых скобках.

  • Перечень необязательных аргументов заключается в квадратные скобки. При вызове функции квадратные скобки вводить не нужно.

  • После :: в угловых скобках указаны типы значений, которые возвращает функция.

Функции разбора согласно регулярному выражению

parse_regex

Разбирает строку value с использованием предоставленного регулярного выражения pattern. Эта функция отличается от функции parse_regex_all тем, что ищет только первое совпадение.

Функция возвращает объект с полями, соответствующими именованным группам. При включенной опции numeric_groups объект также включает поля, ключи которых являются последовательными номерами:

  • поле "0" содержит совпадение полностью;

  • последующие поля содержат захваченные группы по порядку.

Спецификация функции

parse_regex(value: <строка>, pattern: <регулярное выражение>, [numeric_groups: <логическое значение>])
:: <объект>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

value

строка

Строка для поиска.

да

pattern

регулярное выражение

да

numeric_groups

логическое значение

Если true, будет возвращаться каждая захваченная группы в регулярном выражении. Индекс 0 будет содержать совпадение полностью.

false

нет

Примечания

Эта функция имеет особое поведение, о котором следует знать.

  • VRL стремится предоставлять функции специального назначения для разбора общих форматов журналов. Прежде чем использовать функцию parse_regex, проверьте, существует ли уже функция VRL, которая разбирает нужный формат.

  • Если в pattern нет именованных групп и значение numeric_groups равно false, функция возвращает пустой объект.

  • Все значения возвращаются как строки. Рекомендуется преобразовывать значения в нужные типы, используя соответствующие функции.

Ошибки

Функция parse_regex может возвращать ошибки, для которых требуется обработка:

  • Строку value не удалось разобрать с использованием предоставленного шаблона pattern.

Примеры

Разбор с использованием регулярного выражения (с захватом именованной группы)

Example 1. Исходный код
parse_regex!("Connection attempt from 192.0.2.0, from 192.0.2.1.", r'from (?P<ip>\d+\.\d+\.\d+\.\d+)')
Example 2. Результат
{
  "ip": "192.0.2.0"
}

Разбор с использованием регулярного выражения (без захвата именованных групп)

Example 3. Исходный код
parse_regex!("Connection attempt from 192.0.2.0, from 192.0.2.1.", r'from (\d+\.\d+\.\d+\.\d+)', numeric_groups: true)
Example 4. Результат
{
  "0": "from 192.0.2.0",
  "1": "192.0.2.0"
}

parse_regex_all

Разбирает значение с использованием предоставленного регулярного выражения pattern. Эта функция отличается от функции parse_regex тем, что ищет все совпадения, а не только первое.

Функция возвращает массив объектов с полями, соответствующими именованным группам. При включенной опции numeric_groups объекты также включают поля, ключи которых являются последовательными номерами:

  • поле "0" содержит совпадение полностью;

  • последующие поля содержат захваченные группы по порядку.

Спецификация функции

parse_regex_all(value: <строка>, pattern: <регулярное выражение>, [numeric_groups: <логическое значение>])
:: <массив> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

value

строка

Строка для поиска.

да

pattern

регулярное выражение

Регулярное выражение для поиска.

да

numeric_groups

логическое значение

Если true, будет возвращаться каждая захваченная группы в регулярном выражении. Индекс 0 будет содержать совпадение полностью.

false

нет

Примечания

Эта функция имеет особое поведение, о котором следует знать.

  • VRL стремится предоставлять функции специального назначения для разбора общих форматов журналов. Прежде чем использовать функцию parse_regex, проверьте, существует ли уже функция VRL, которая разбирает нужный формат.

  • Если в pattern нет именованных групп и значение numeric_groups равно false, функция возвращает массив пустых объектов.

  • Все значения возвращаются как строки. Рекомендуется преобразовывать значения в нужные типы, используя соответствующие функции.

Ошибки

Функция parse_regex_all может возвращать ошибки, для которых требуется обработка:

  • значение не удалось разобрать с использованием предоставленного шаблона pattern.

Примеры

Разбор с использованием регулярного выражения (все совпадения)

Example 5. Исходный код
parse_regex_all!("Connection attempt from 192.0.2.0, from 192.0.2.1.", r'from (?P<ip>\d+\.\d+\.\d+\.\d+)', numeric_groups: true)
Example 6. Результат
[
  {
    "0": "from 192.0.2.0",
    "1": "192.0.2.0",
    "ip": "192.0.2.0"
  },
  {
    "0": "from 192.0.2.1",
    "1": "192.0.2.1",
    "ip": "192.0.2.1"
  }
]

Функции разбора форматов логов

parse_apache_log

Разбирает строки журнала доступа и ошибок Apache. Строки могут иметь формат common, combined или error.

Спецификация функции

parse_apache_log(значение: <строка>, формат: <строка>, [формат_метки_времени: <строка>])
:: <объект>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для разбора.

да

format

строка

Формат, используемый для разбора журнала.

да

формат_метки_времени

строка

Формат даты/времени, используемый для кодирования метки времени. Время разбирается в локальном часовом поясе, если метка времени не указывает часовой пояс.

%d/%b/%Y:%T %z

нет

Примечания

У этой функции есть особое поведение, о котором следует знать:

  • Отсутствие информации в сообщении журнала может быть обозначено -. Эти поля опущены в результате.

Ошибки

Функция parse_apache_log может возвращать ошибки, для которых требуется обработка:

  • значение не соответствует указанному формату.

  • формат_метки_времени не является допустимой строкой формата.

  • Метку времени в значение не удалось разобрать с использованием предоставленного формата метки времени.

Примеры

Разбор строки в формате журнала Apache (common)

Example 7. Исходный код
parse_apache_log!("127.0.0.1 bob frank [10/Oct/2000:13:55:36 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 2326", format: "common")
Example 8. Результат
{
"host": "127.0.0.1",
"identity": "bob",
"user": "frank",
"timestamp": "2000-10-10T20:55:36Z",
"message": "GET /apache_pb.gif HTTP/1.0",
"method": "GET",
"path": "/apache_pb.gif",
"protocol": "HTTP/1.0",
"status": 200,
"size": 2326
}

Разбор строки в формате журнала Apache (combined)

Example 9. Исходный код
parse_apache_log!(
s'127.0.0.1 bob frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326 "http://www.seniorinfomediaries.com/vertical/channels/front-end/bandwidth" "Mozilla/5.0 (X11; Linux i686; rv:5.0) Gecko/1945-10-12 Firefox/37.0"',
"combined",
)
Example 10. Результат
{
"host": "127.0.0.1",
"identity": "bob",
"user": "frank",
"timestamp": "2000-10-10T20:55:36Z",
"message": "GET /apache_pb.gif HTTP/1.0",
"method": "GET",
"path": "/apache_pb.gif",
"protocol": "HTTP/1.0",
"status": 200,
"size": 2326,
"referrer": "http://www.seniorinfomediaries.com/vertical/channels/front-end/bandwidth",
"agent": "Mozilla/5.0 (X11; Linux i686; rv:5.0) Gecko/1945-10-12 Firefox/37.0"
}

Разбор строки в формате журнала Apache (ошибка)

Example 11. Исходный код
parse_apache_log!(
s'[01/Mar/2021:12:00:19 +0000] [ab:alert] [pid 4803:tid 3814] [client 147.159.108.175:24259] I will bypass the haptic COM bandwidth, that should matrix the CSS driver!',
"error"
)
Example 12. Результат
{
"client": "147.159.108.175",
"message": "I will bypass the haptic COM bandwidth, that should matrix the CSS driver!",
"module": "ab",
"pid": 4803,
"port": 24259,
"severity": "alert",
"thread": "3814",
"timestamp": "2021-03-01T12:00:19Z"
}

rv_parse_avro

Разбирает значение как файл формата Apache Avro, который содержит метаданные со схемой. Если сообщение не содержит схемы, используйте функцию rv_parse_avro_raw.

Спецификация функции

rv_parse_avro(значение: <строка>, [reader_schema: <строка>])
:: <массив объектов>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строковое представление сообщения Avro

да

reader_schema

JSON

Схема для считывания в формате JSON

нет

Примечания

Особенности функции, о которых нужно знать:

  • Использование схемы считывания (параметр reader_schema) может замедлить выполнение функции.

  • Тип Decimal в сообщениях Avro не поддерживается.

Ошибки

Функция rv_parse_avro может возвращать ошибки, для которых требуется обработка:

  • значение не является корректным сообщением Avro;

  • значение закодировано не в UTF-8;

  • reader_schema не является строкой;

  • невозможно разобрать предоставленную reader_schema;

  • значения типов TimeMicros, TimeMillis, Float и Double в разобранном сообщении не являются числовыми.

Примеры

Базовый разбор

Example 13. Исходный код
rv_parse_avro!(.message)
Example 14. Результат
"массив объектов"

С указанием схемы

Example 15. Исходный код
rv_parse_avro!(.message, reader_schema: "{"type": "record", "fields" : [{ "name" : "test" , "type" : "string" }]}")
Example 16. Результат
[{test: "value"}]

rv_parse_avro_raw

Разбирает значение как отдельную запись Apache Avro, сериализованную без заголовков или встроенной схемы. Функция требует предоставлять схему расшифровки данных.

Спецификация функции

rv_parse_avro_raw(значение: <строка>, decoder_schema: <avro_schema>, [reader_schema: <строка>])
:: <объект>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строковое представление сообщения Avro

да

decoder_schema

строка

Схема для расшифровки данных

да

reader_schema

JSON

Схема в формате JSON для валидации расшифрованных данных

нет

Примечания

Особенности функции, о которых нужно знать:

  • Использование схемы считывания (параметр reader_schema) может замедлить выполнение функции.

  • Тип Decimal в сообщениях Avro не поддерживается.

Ошибки

Функция rv_parse_avro_raw может возвращать ошибки, для которых требуется обработка:

  • значение не является корректным сообщением Avro;

  • decoder_schema не является строкой;

  • reader_schema не является строкой;

  • невозможно разобрать предоставленную decoder_schema;

  • невозможно разобрать предоставленную reader_schema;

  • значения типов TimeMicros, TimeMillis, Float и Double в разобранном сообщении не являются числовыми.

Примеры

Базовый разбор

Example 17. Исходный код
rv_parse_avro_raw!(.message, decoder_schema: "{"type": "record", "fields" : [{ "name" : "test" , "type" : "string" }, { "name" : "test2" , "type" : "string" }]}")
Example 18. Результат
{test: "value", test2: "value"}"

С указанием схемы считывания

Example 19. Исходный код
parse_avro_raw!(.message, decoder_schema: s'{"type": "record", "fields" : [{ "name" : "test" , "type" : "string" }, { "name" : "test2" , "type" : "string" }]}', reader_scheme: s'{"type": "record", "fields" : [{ "name" : "test" , "type" : "string" }]}')
Example 20. Результат
{test: "value"}

parse_aws_alb_log

Разбирает значение в формате журнала доступа Application Load Balancer в AWS (Amazon Web Services).

Спецификация функции

parse_aws_alb_log(значение: <строка>)
:: <объект>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Журнал доступа Application Load Balancer.

да

Ошибки

Функция parse_aws_alb_log может возвращать ошибки, для которых требуется обработка:

  • значение не соответствует указанному формату лога AWS ALB.

Примеры

Разбор лога AWS ALB

Example 21. Исходный код
parse_aws_alb_log!(
"http 2018-11-30T22:23:00.186641Z app/my-loadbalancer/50dc6c495c0c9188 192.168.131.39:2817 - 0.000 0.001 0.000 200 200 34 366 \"GET http://www.example.com:80/ HTTP/1.1\" \"curl/7.46.0\" - - arn:aws:elasticloadbalancing:us-east-2:123456789012:targetgroup/my-targets/73e2d6bc24d8a067 \"Root=1-58337364-23a8c76965a2ef7629b185e3\" \"-\" \"-\" 0 2018-11-30T22:22:48.364000Z \"forward\" \"-\" \"-\" \"-\" \"-\" \"-\" \"-\""
)
Example 22. Результат
{
"type": "http",
"timestamp": "2018-11-30T22:23:00.186641Z",
"elb": "app/my-loadbalancer/50dc6c495c0c9188",
"client_host": "192.168.131.39:2817",
"target_host": null,
"request_processing_time": 0,
"target_processing_time": 0.001,
"response_processing_time": 0,
"elb_status_code": "200",
"target_status_code": "200",
"received_bytes": 34,
"sent_bytes": 366,
"request_method": "GET",
"request_url": "http://www.example.com:80/",
"request_protocol": "HTTP/1.1",
"user_agent": "curl/7.46.0",
"ssl_cipher": null,
"ssl_protocol": null,
"target_group_arn": "arn:aws:elasticloadbalancing:us-east-2:123456789012:targetgroup/my-targets/73e2d6bc24d8a067",
"trace_id": "Root=1-58337364-23a8c76965a2ef7629b185e3",
"domain_name": null,
"chosen_cert_arn": null,
"matched_rule_priority": "0",
"request_creation_time": "2018-11-30T22:22:48.364000Z",
"actions_executed": "forward",
"redirect_url": null,
"error_reason": null,
"target_port_list": [],
"target_status_code_list": [],
"classification": null,
"classification_reason": null
}

parse_aws_cloudwatch_log_subscription_message

Разбирает события журналов AWS CloudWatch, настроенных через подписки Cloudwatch, из источника aws_kinesis_firehose.

Спецификация функции

parse_aws_cloudwatch_log_subscription_message(значение: <строка>)
:: <объект>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строковое представление сообщения для разбора.

да

Ошибки

Функция parse_aws_cloudwatch_log_subscription_message может возвращать ошибки, для которых требуется обработка:

  • значение не является правильно отформатированным сообщением подписки AWS Cloudwatch Log.

Примеры

Разбор сообщения подписки AWS Cloudwatch Log

Example 23. Исходный код
parse_aws_cloudwatch_log_subscription_message!(.message)
Example 24. Результат
{
"owner": "111111111111",
"message_type": "DATA_MESSAGE",
"log_group": "test",
"log_stream": "test",
"subscription_filters": [
"Destination"
],
"log_events": [
{
"id": "35683658089614582423604394983260738922885519999578275840",
"message": "{\"bytes\":26780,\"datetime\":\"14/Sep/2020:11:45:41 -0400\",\"host\":\"157.130.216.193\",\"method\":\"PUT\",\"protocol\":\"HTTP/1.0\",\"referer\":\"https://www.principalcross-platform.io/markets/ubiquitous\",\"request\":\"/expedite/convergence\",\"source_type\":\"stdin\",\"status\":301,\"user-identifier\":\"-\"}",
"timestamp": "2020-09-14T19:09:29.039Z"
}
]
}

parse_aws_vpc_flow_log

Разбирает значение в формате журналов потокового контроля AWS Virtual Private Cloud (VPC Flow Logs).

Спецификация функции

parse_aws_vpc_flow_log(значение: <строка>, [формат: <строка>])
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Журнал потоков VPC.

да

формат

строка

Формат журнала потоков VPC.

нет

Ошибки

Функция parse_aws_vpc_flow_log может возвращать ошибки, для которых требуется обработка:

  • значение имеет неправильный формат журнала потоков VPC AWS.

Примеры

Разбор журнала потоков VPC AWS (формат по умолчанию)

Example 25. Исходный код
parse_aws_vpc_flow_log!("2 123456789010 eni-1235b8ca123456789 - - - - - - 1431280876 1431280934 - NODATA")
Example 26. Результат
{
"version": 2,
"account_id": 123456789010,
"interface_id": "eni-1235b8ca123456789",
"srcaddr": null,
"dstaddr": null,
"srcport": null,
"dstport": null,
"protocol": null,
"packets": null,
"bytes": null,
"start": 1431280876,
"end": 1431280934,
"action": null,
"log_status": "NODATA"
}

Разбор журнала потоков VPC AWS (пользовательский формат)

Example 27. Исходный код
parse_aws_vpc_flow_log!(
"- eni-1235b8ca123456789 10.0.1.5 10.0.0.220 10.0.1.5 203.0.113.5",
"instance_id interface_id srcaddr dstaddr pkt_srcaddr pkt_dstaddr"
)
Example 28. Результат
{
"instance_id": null,
"interface_id": "eni-1235b8ca123456789",
"srcaddr": "10.0.1.5",
"dstaddr": "10.0.0.220",
"pkt_srcaddr": "10.0.1.5",
"pkt_dstaddr": "203.0.113.5"
}

parse_cef

Разбирает значение в формате CEF (Common Event Format). Игнорирует все данные до заголовка CEF.

Рекомендуется использовать функцию rv_parse_cef, которая поддерживает заголовки syslog.

Спецификация функции

parse_cef(значение: <строка>, [translate_custom_fields: <логическое значение>])
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для разбора

да

translate_custom_fields

логическое значение

Преобразовывать пользовательские пары полей в формат ключ: значение

false

нет

Примечания

У этой функции есть специальное поведение, которое следует учитывать:

  • Все значения возвращаются в виде строк. Рекомендуется вручную приводить значения к желаемым типам при необходимости.

  • Обрамляющие кавычки удаляются из значений.

  • Пустые значения возвращаются в виде пустых строк.

Ошибки

Функция parse_cef может возвращать ошибки, для которых требуется обработка:

  • Значение имеет неправильный формат строки CEF.

Примеры

Разбор сообщения, сгенерированного Privileged Threat Analytics (PTA)

Example 29. Исходный код
parse_cef!(
"CEF:0|CyberArk|PTA|12.6|1|Suspected credentials theft|8|suser=mike2@prod1.domain.com shost=prod1.domain.com src=1.1.1.1 duser=andy@dev1.domain.com dhost=dev1.domain.com dst=2.2.2.2 cs1Label=ExtraData cs1=None cs2Label=EventID cs2=52b06812ec3500ed864c461e deviceCustomDate1Label=detectionDate deviceCustomDate1=1388577900000 cs3Label=PTAlink cs3=https://1.1.1.1/incidents/52b06812ec3500ed864c461e cs4Label=ExternalLink cs4=None"
)
Example 30. Результат
{
"cefVersion": "0",
"deviceVendor": "CyberArk",
"deviceProduct": "PTA",
"deviceVersion": "12.6",
"deviceEventClassId": "1",
"name": "Suspected credentials theft",
"severity": "8",
"suser": "mike2@prod1.domain.com",
"shost": "prod1.domain.com",
"src": "1.1.1.1",
"duser": "andy@dev1.domain.com",
"dhost": "dev1.domain.com",
"dst": "2.2.2.2",
"cs1Label": "ExtraData",
"cs1": "None",
"cs2Label": "EventID",
"cs2": "52b06812ec3500ed864c461e",
"deviceCustomDate1Label": "detectionDate",
"deviceCustomDate1": "1388577900000",
"cs3Label": "PTAlink",
"cs3": "https://1.1.1.1/incidents/52b06812ec3500ed864c461e",
"cs4Label": "ExternalLink",
"cs4": "None"
}

Сообщение с заголовком syslog, которое игнорируется

Example 31. Исходный код
parse_cef!(
"Sep 29 08:26:10 host CEF:1|Security|threatmanager|1.0|100|worm successfully stopped|10|src=10.0.0.1 dst=2.1.2.2 spt=1232"
)
Example 32. Результат
{
"cefVersion": "1",
"deviceVendor": "Security",
"deviceProduct": "threatmanager",
"deviceVersion": "1.0",
"deviceEventClassId": "100",
"name": "worm successfully stopped",
"severity": "10",
"src": "10.0.0.1",
"dst": "2.1.2.2",
"spt": "1232"
}

Преобразование пользовательских полей

Example 33. Исходный код
parse_cef!(
"CEF:0|Dev|firewall|2.2|1|Connection denied|5|c6a1=2345:0425:2CA1:0000:0000:0567:5673:23b5 c6a1Label=Device IPv6 Address",
translate_custom_fields: true
)
Example 34. Результат
{
"cefVersion": "0",
"deviceVendor": "Dev",
"deviceProduct": "firewall",
"deviceVersion": "2.2",
"deviceEventClassId": "1",
"name": "Connection denied",
"severity": "5",
"Device IPv6 Address": "2345:0425:2CA1:0000:0000:0567:5673:23b5"
}

rv_parse_cef

Разбирает значение в формате Common Event Format (CEF). Поддерживает и обрабатывает необязательный заголовок syslog.

Спецификация функции

rv_parse_cef(значение: <строка>)
:: <объект>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строковое представление записи CEF

да

Ошибки

Функция rv_parse_cef может возвращать ошибки, для которых требуется обработка:

  • строка значения не начинается с обязательного префикса CEF:;

  • строка значения не содержит обязательных полей и не является корректной записью CEF.

Примеры

Базовый разбор

Example 35. Исходный код
rv_parse_cef!(s'CEF:0|Microsoft|Microsoft Windows||Microsoft-Windows-Security-Auditing:4624|An account was successfully logged on.|Low| eventId=1013540004 externalId=4624')
Example 36. Результат
{
    "deviceVendor": "Microsoft",
    "deviceProduct": "Microsoft Windows",
    "deviceVersion": "",
    "deviceEventClassId": "Microsoft-Windows-Security-Auditing:4624",
    "name": "An account was successfully logged on.",
    "severity": "Low",
    "eventId": "1013540004",
    "externalId": "4624"
}

Сообщение с заголовком syslog

Example 37. Исходный код
value = r#"<134>1 2022-02-14T03:17:30-08:00 TEST CEF:0|Vendor|Product|20.0.560|600|User Signed In|3|src=127.0.0.1 "#
rv_parse_cef!(value)
Example 38. Результат
{
    ahost: "TEST",
    at: "2022-02-14T03:17:30-08:00",
    deviceProduct: "Product",
    deviceVendor: "Vendor",
    deviceVersion: "20.0.560",
    name: "User Signed In",
    severity: "3",
    signatureId: "600",
    src: "127.0.0.1",
    syslog_facility: "16",
    syslog_priority: "134",
    syslog_severity: "6",
})

parse_common_log

Разбирает значение с использованием формата общего журнала Apache (Common Log Format, CLF).

Спецификация функции

parse_common_log(значение: <строка>, [формат_метки_времени: <строка>])
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для разбора.

да

формат_метки_времени

строка

Формат даты/времени для кодирования метки времени.

%d/%b/%Y:%T %z

нет

Примечания

У этой функции есть специальное поведение, которое следует учитывать:

  • Отсутствующая информация в журнальной записи может быть обозначена -. Эти поля опускаются в результате.

Ошибки

Функция parse_common_log может возвращать ошибки, для которых требуется обработка:

  • значение не соответствует формату общего журнала.

  • формат_метки_времени не является допустимой строкой формата.

  • Метку времени в значении не удается разобрать с использованием предоставленного формата_метки_времени.

Примеры

Разбор сообщения в формате общего журнала (с форматом метки времени по умолчанию)

Example 39. Исходный код
parse_common_log!("127.0.0.1 bob frank [10/Oct/2000:13:55:36 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 2326")
Example 40. Результат
{
"host": "127.0.0.1",
"identity": "bob",
"user": "frank",
"timestamp": "2000-10-10T20:55:36Z",
"message": "GET /apache_pb.gif HTTP/1.0",
"method": "GET",
"path": "/apache_pb.gif",
"protocol": "HTTP/1.0",
"status": 200,
"size": 2326
}

Разбор сообщения в формате общего журнала с пользовательским форматом метки времени

Example 41. Исходный код
parse_common_log!(
"127.0.0.1 bob frank [2000-10-10T20:55:36Z] \"GET /apache_pb.gif HTTP/1.0\" 200 2326",
"%+"
)
Example 42. Результат
{
"host": "127.0.0.1",
"identity": "bob",
"user": "frank",
"timestamp": "2000-10-10T20:55:36Z",
"message": "GET /apache_pb.gif HTTP/1.0",
"method": "GET",
"path": "/apache_pb.gif",
"protocol": "HTTP/1.0",
"status": 200,
"size": 2326
}

rv_extract_from_dit

Извлекает домен и имя пользователя из записи DIT (Data Information Tree), используемой в протоколе LDAP.

Спецификация функции

rv_extract_from_dit(значение: <строка>)
:: <строка>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строковое представление записи DIT

да

Примечания

Особенность функции, о которой нужно знать:

  • Результат возвращается в виде JSON-объекта с полями "username" и "domain".

  • Имя пользователя и домен возвращаются в нижнем регистре.

Ошибки

Функция rv_extract_from_dit может возвращать ошибки, для которых требуется обработка:

  • Значение закодировано не в UTF-8.

  • Значение не является корректной записью DIT.

Пример

Example 43. Исходный код
extract_from_dit("CN=Dev-India,OU=Distribution Groups,DC=gp,DC=gl,DC=example,DC=com"
Example 44. Результат
{"username": "dev-india", "domain": "gp.gl.example.com"}

parse_glog

Разбирает значение с использованием формата glog (Google Logging Library).

Спецификация функции

parse_glog(значение: <строка>)
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для разбора.

да

Ошибки

Функция parse_glog может возвращать ошибки, для которых требуется обработка:

  • значение не соответствует формату glog.

Примеры

Разбор через формат glog

Example 45. Исходный код
parse_glog!("I20210131 14:48:54.411655 15520 main.c++:9] Hello world!")
Example 46. Результат
{
"level": "info",
"timestamp": "2021-01-31T14:48:54.411655Z",
"id": 15520,
"file": "main.c++",
"line": 9,
"message": "Hello world!"
}

parse_grok

Разбирает значение, используя формат grok. Поддерживаются все шаблоны grok.

Рекомендуется использовать шаблоны Grok, которые поддерживаются сообществом. Такие шаблоны, скорее всего, будут проверены и улучшены в будущем, в отличие от пользовательских шаблонов.

Спецификация функции

parse_grok(значение: <строка>, pattern: <строка>)
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для разбора.

да

pattern

строка

Шаблон Grok.

да

Ошибки

Функция parse_grok может возвращать ошибки, для которых требуется обработка:

  • значение не удается разобрать с использованием предоставленного шаблона pattern.

Примеры

Разбор с использованием Grok

Example 47. Исходный код
parse_grok!(
"2020-10-02T23:22:12.223222Z info Hello world",
"%{TIMESTAMP_ISO8601:timestamp} %{LOGLEVEL:level} %{GREEDYDATA:message}"
)
Example 48. Результат
{
"timestamp": "2020-10-02T23:22:12.223222Z",
"level": "info",
"message": "Hello world"
}

parse_groks

Разбирает значение, используя несколько шаблонов grok. Поддерживаются все шаблоны grok.

Рекомендуется использовать шаблоны Grok, которые поддерживаются сообществом. Такие шаблоны, скорее всего, будут проверены и улучшены в будущем, в отличие от пользовательских шаблонов.

Спецификация функции

parse_groks(значение: <строка>, patterns: <массив>, [aliases: <объект>])
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для разбора.

да

patterns

массив

Шаблоны Grok, которые применяются последовательно до первого совпадения.

да

aliases

объект

Общий набор псевдонимов Grok, на которые можно ссылаться в шаблонах для их упрощения.

true

нет

Ошибки

Функция parse_groks может возвращать ошибки, для которых требуется обработка:

  • значение не удается разобрать с использованием предоставленных шаблонов.

Примеры

Разбор с использованием нескольких шаблонов Grok

Example 49. Исходный код
parse_groks!(
"2020-10-02T23:22:12.223222Z info Hello world",
patterns: [
"%{common_prefix} %{_status} %{_message}",
"%{common_prefix} %{_message}",
],
aliases: {
"common_prefix": "%{_timestamp} %{_loglevel}",
"_timestamp": "%{TIMESTAMP_ISO8601:timestamp}",
"_loglevel": "%{LOGLEVEL:level}",
"_status": "%{POSINT:status}",
"_message": "%{GREEDYDATA:message}"
}
)
Example 50. Результат
{
"timestamp": "2020-10-02T23:22:12.223222Z",
"level": "info",
"message": "Hello world"
}

parse_klog

Разбирает значение в формате klog, используемом компонентами Kubernetes.

Спецификация функции

parse_klog(значение: <строка>)
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для разбора.

да

Ошибки

Функция parse_klog может возвращать ошибки, для которых требуется обработка:

  • значение не соответствует формату klog.

Примеры

Разбор по формату klog

Example 51. Исходный код
parse_klog!("I0505 17:59:40.692994 28133 klog.go:70] hello from klog")
Example 52. Результат
{
"file": "klog.go",
"id": 28133,
"level": "info",
"line": 70,
"message": "hello from klog",
"timestamp": "2023-05-05T17:59:40.692994Z"
}

rv_parse_leef

Разбирает значение в формате Log Event Extended Format (LEEF).

Спецификация функции

rv_parse_leef(значение: <строка>)
:: <объект>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строковое представление сообщения LEEF

да

Ошибки

Функция rv_parse_leef может возвращать ошибки, для которых требуется обработка:

  • значение не является корректным сообщением LEEF.

Пример

Сообщение LEEF с заголовком syslog и атрибутами события, разделёнными символом ^

Example 53. Исходный код
rv_parse_leef!("<13>1 2024-07-18T11:07:53.520Z 192.168.1.1 LEEF:2.0|Microsoft|MSExchange|2007|7732|^|dvchost=www.example.com^msg=io\t|p")
Example 54. Результат
{
    "syslog_facility": "1",
    "syslog_priority": "13",
    "syslog_severity": "5",
    "at": "2024-07-18T11:07:53.520Z",
    "ahost": "192.168.1.1",
    "dvchost": "www.example.com",
    "msg": "io\t|p",
    "deviceVendor": "Microsoft",
    "eventName": "7732",
    "productName": "MSExchange",
    "productVersion": "2007",
}

parse_linux_authorization

Разбирает журналы авторизации Linux, которые обычно находятся в каталогах /var/log/auth.log (в системах на основе Debian) или /var/log/secure (в системах на основе RedHat), в соответствии с форматом syslog.

Спецификация функции

parse_linux_authorization(значение: <строка>)
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Текст, содержащий сообщение для разбора.

да

Примечания

Эта функция имеет особое поведение: если в сообщении не указан год, он определяется автоматически:

  • Если текущий месяц — январь, а сообщение относится к декабрю, то используется предыдущий год.

  • В противном случае используется текущий год.

Ошибки

Функция parse_linux_authorization может возвращать ошибки, для которых требуется обработка:

  • значение не является правильно отформатированным сообщением syslog.

Примеры

Разбор события авторизации Linux

Example 55. Исходный код
parse_linux_authorization!(
s'Mar 23 01:49:58 localhost sshd[1111]: Accepted publickey for eng from 10.1.1.1 port 8888 ssh2: RSA SHA256:foobar'
)
Example 56. Результат
{
"appname": "sshd",
"hostname": "localhost",
"message": "Accepted publickey for eng from 10.1.1.1 port 8888 ssh2: RSA SHA256:foobar",
"procid": 1111,
"timestamp": "2023-03-23T01:49:58Z"
}

parse_logfmt

Разбирает значение в формате logfmt. Функция аналогична parse_key_value, но разбирает только сообщения со стандартными разделителями.

Спецификация функции

parse_logfmt(значение: <строка>)
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для разбора.

Ключи и значения могут быть заключены в двойные кавычки ". Символ " может быть экранирован символом \.

да

Примечания

У этой функции есть специальное поведение, которое следует учитывать:

  • Согласно спецификации logfmt, ключами без значений присваивается логическое значение true.

Ошибки

Функция parse_logfmt может возвращать ошибки, для которых требуется обработка:

  • значение не является правильно отформатированной строкой "ключ — значение" (logfmt).

Примеры

Разбор лога в формате logfmt

Example 57. Исходный код
parse_logfmt!(
"@timestamp=\"Sun Jan 10 16:47:39 EST 2021\" level=info msg=\"Stopping all fetchers\" tag#production=stopping_fetchers id=ConsumerFetcherManager-1382721708341 module=kafka.consumer.ConsumerFetcherManager"
)
Example 58. Результат
{
"@timestamp": "Sun Jan 10 16:47:39 EST 2021",
"level": "info",
"msg": "Stopping all fetchers",
"tag#production": "stopping_fetchers",
"id": "ConsumerFetcherManager-1382721708341",
"module": "kafka.consumer.ConsumerFetcherManager"
}

rv_parse_msgpack

Разбирает значение в формате MessagePack.

Спецификация функции

rv_parse_msgpack(значение: <строка>)
:: <объект>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строковое представление MessagePack

да

Примечания

Особенности функции, о которых нужно знать:

  • Возвращаются только типы MessagePack. Дополнительные типы (extension) не поддерживаются. Если нужно преобразовать string в timestamp, используйте функцию parse_timestamp.

  • В типе map поддерживаются только строковые ключи.

Ошибки

Функция rv_parse_msgpack может возвращать ошибки, для которых требуется обработка:

  • значение не является массивом байтов.

Примеры

Преобразование массива байтов

Example 59. Исходный код
rv_parse_msgpack!([
    135, 163, 105, 110, 116, 1, 165, 102, 108, 111, 97, 116, 203, 63, 224, 0, 0, 0, 0, 0, 0,
    167, 98, 111, 111, 108, 101, 97, 110, 195, 164, 110, 117, 108, 108, 192, 166, 115, 116,
    114, 105, 110, 103, 167, 102, 111, 111, 32, 98, 97, 114, 165, 97, 114, 114, 97, 121, 146,
    163, 102, 111, 111, 163, 98, 97, 114, 166, 111, 98, 106, 101, 99, 116, 130, 163, 102, 111,
    111, 1, 163, 98, 97, 122, 203, 63, 224, 0, 0, 0, 0, 0, 0,
])
Example 60. Результат
{
    "int": 1,
    "float": 0.5,
    "boolean": true,
    "null": null,
    "string": "foo bar",
    "array": [
        "foo",
        "bar"
    ],
    "object": {
        "foo": 1,
        "baz": 0.5
}

Преобразование после декодирования из Base64

Example 61. Исходный код
rv_parse_msgpack!(decode_base64!("3wAAAAGlZmllbGSldmFsdWU="))
Example 62. Результат
{"field": "value"}

rv_parse_msgpack_batch

Разбирает значение, которое состоит из нескольких сообщений в формате MessagePack.

Спецификация функции

rv_parse_msgpack_batch(значение: <строка>)
:: <массив объектов>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строковое представление пакета объектов MessagePack

да

Примечания

Особенности функции, о которых нужно знать:

  • Возвращаются только типы MessagePack. Дополнительные типы (extension) не поддерживаются. Если нужно преобразовать string в timestamp, используйте функцию parse_timestamp.

  • В типе map поддерживаются только строковые ключи.

Ошибки

Функция rv_parse_msgpack_batch может возвращать ошибки, для которых требуется обработка:

  • значение не является массивом байтов.

Примеры

Преобразование массива байтов

Example 63. Исходный код
rv_parse_msgpack_batch!([
    135, 163, 105, 110, 116, 1, 165, 102, 108, 111, 97, 116, 203, 63, 224, 0, 0, 0, 0, 0, 0,
    167, 98, 111, 111, 108, 101, 97, 110, 195, 164, 110, 117, 108, 108, 192, 166, 115, 116,
    114, 105, 110, 103, 167, 102, 111, 111, 32, 98, 97, 114, 165, 97, 114, 114, 97, 121, 146,
    163, 102, 111, 111, 163, 98, 97, 114, 166, 111, 98, 106, 101, 99, 116, 130, 163, 102, 111,
    111, 1, 163, 98, 97, 122, 203, 63, 224, 0, 0, 0, 0, 0, 0,
    135, 163, 105, 110, 116, 1, 165, 102, 108, 111, 97, 116, 203, 63, 224, 0, 0, 0, 0, 0, 0,
    167, 98, 111, 111, 108, 101, 97, 110, 195, 164, 110, 117, 108, 108, 192, 166, 115, 116,
    114, 105, 110, 103, 167, 102, 111, 111, 32, 98, 97, 114, 165, 97, 114, 114, 97, 121, 146,
    163, 102, 111, 111, 163, 98, 97, 114, 166, 111, 98, 106, 101, 99, 116, 130, 163, 102, 111,
    111, 1, 163, 98, 97, 122, 203, 63, 224, 0, 0, 0, 0, 0, 0,
])
Example 64. Результат
[{
    "int": 1,
    "float": 0.5,
    "boolean": true,
    "null": null,
    "string": "foo bar",
    "array": [
        "foo",
        "bar"
    ],
    "object": {
        "foo": 1,
        "baz": 0.5
    }
},
{
    "int": 1,
    "float": 0.5,
    "boolean": true,
    "null": null,
    "string": "foo bar",
    "array": [
        "foo",
        "bar"
    ],
    "object": {
        "foo": 1,
        "baz": 0.5
    }
}]

Преобразование после декодирования из Base64

Example 65. Исходный код
rv_parse_msgpack!(decode_base64!("3wAAAAGlZmllbGSldmFsdWXfAAAAAaVmaWVsZKV2YWx1ZQ=="))
Example 66. Результат
[{"field": "value"}, {"field": "value"}]

rv_parse_netflow

Разбирает значение в формате пакетов NetFlow.

Спецификация функции

rv_parse_netflow(значение: <строка>)
:: <массив объектов>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строковое представление пакетов NetFlow.

да

Ошибки

Функция rv_parse_netflow может возвращать ошибки, для которых требуется обработка:

  • значение не является правильным нетфлоу пакетом

Примеры

Разбор пакетов NetFlow

Example 67. Исходный код
rv_parse_netflow!(decode_base64!("AAUCAAMABAAFAAYHCAkAAQIDBAUGBwgJAAECAwQFBgcICQABAgMEBQYHCAkAAQIDBAUGBwgJAAECAwQFBgcICQABAgMEBQYH"))
Example 68. Результат
[
  {
    "V5": {
      "body": {
        "d_octets": 66051,
        "d_pkts": 101124105,
        "dst_addr": "4.5.6.7",
        "dst_as": 515,
        "dst_mask": 5,
        "dst_port": 1029,
        "first": {
          "nanos": 87000000,
          "secs": 67438
        },
        "input": 515,
        "last": {
          "nanos": 553000000,
          "secs": 134807
        },
        "next_hop": "8.9.0.1",
        "output": 1029,
        "pad1": 6,
        "pad2": 1543,
        "protocol_number": 8,
        "protocol_type": "EGP",
        "src_addr": "0.1.2.3",
        "src_as": 1,
        "src_mask": 4,
        "src_port": 515,
        "tcp_flags": 7,
        "tos": 9
      },
      "header": {
        "count": 512,
        "engine_id": 7,
        "engine_type": 6,
        "flow_sequence": 33752069,
        "sampling_interval": 2057,
        "sys_up_time": {
          "nanos": 672000000,
          "secs": 50332
        },
        "unix_nsecs": 134807553,
        "unix_secs": 83887623,
        "version": 5
      }
    }
  }
]

parse_nginx_log

Разбирает строки журналов доступа и ошибок Nginx. Строки могут быть в формате combined или error.

Спецификация функции

parse_nginx_log(значение: <строка>, формат: <строка>, [формат_метки_времени: <строка>])
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для разбора.

да

формат

строка

Формат, используемый для разбора журнала.

да

формат_метки_времени

строка

Формат даты/времени, используемый для кодирования метки времени. Если в метке времени не указан часовой пояс, время разбирается как локальное. Формат по умолчанию %d/%b/%Y:%T %z для комбинированных журналов и %Y/%m/%d %H:%M:%S для журналов ошибок.

%d/%b/%Y:%T %z

нет

Примечания

Эта функция имеет особое поведение, о котором следует знать.

  • Отсутствующая информация в сообщении может быть обозначена -. Эти поля опускаются в результате.

Ошибки

Функция parse_nginx_log может возвращать ошибки, для которых требуется обработка:

  • значение не соответствует указанному формату.

  • формат_метки_времени не является допустимой строкой формата.

  • Метка времени в значении не удается разобрать с использованием предоставленного формата_метки_времени.

Примеры

Разбор в формате журнала Nginx (комбинированном)

Example 69. Исходный код
parse_nginx_log!(
s'172.17.0.1 - alice [01/Apr/2021:12:02:31 +0000] "POST /not-found HTTP/1.1" 404 153 "http://localhost/somewhere" "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36" "2.75"',
"combined",
)
Example 70. Результат
{
"client": "172.17.0.1",
"user": "alice",
"timestamp": "2021-04-01T12:02:31Z",
"request": "POST /not-found HTTP/1.1",
"method": "POST",
"path": "/not-found",
"protocol": "HTTP/1.1",
"status": 404,
"size": 153,
"referer": "http://localhost/somewhere",
"agent": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"compression": "2.75"
}

Разбор в формате журнала ошибок Nginx

Example 71. Исходный код
parse_nginx_log!(
s'2021/04/01 13:02:31 [error] 31#31: *1 open() "/usr/share/nginx/html/not-found" failed (2: No such file or directory), client: 172.17.0.1, server: localhost, request: "POST /not-found HTTP/1.1", host: "localhost:8081"',
"error"
)
Example 72. Результат
{
"timestamp": "2021-04-01T13:02:31Z",
"severity": "error",
"pid": 31,
"tid": 31,
"cid": 1,
"message": "open() \"/usr/share/nginx/html/not-found\" failed (2: No such file or directory)",
"client": "172.17.0.1",
"server": "localhost",
"request": "POST /not-found HTTP/1.1",
"host": "localhost:8081"
}

parse_proto

Разбирает значение как payload — полезную нагрузку Protocol Buffers.

Спецификация функции

parse_proto(значение: <строка>, файл_дескрипторов: <строка>, тип_сообщения: <строка>)
:: <объект>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Полезная нагрузка Protocol Buffers для разбора.

да

файл_дескрипторов

строка

Путь к файлу набора дескрипторов Protocol Buffers. Должен быть строковым литерал. Этот файл является результатом работы команды protoc -o.

да

тип_сообщения

строка

Имя типа сообщения, используемого для сериализации. Должно быть строковым литералом.

да

Примечание

Функция разбирает и возвращает только сообщения (message) Protocol Buffers.

Ошибки

Функция encode_proto может возвращать ошибки, для которых требуется обработка:

  • Значение не является валидным payload Protocol Buffers.

  • Файл, указанный в аргументе файл_дескрипторов, не существует.

  • Тип сообщения, указанный в аргументе тип_сообщения, отсутствует в файле дескрипторов.

Пример

Example 73. Исходный код
.payload = encode_base64(encode_proto!({"name": "someone", "phones": [{"number": "123456"}]}, "resources/protobuf_descriptor_set.desc", "test_protobuf.Person"))
Example 74. Результат
Cgdzb21lb25lIggKBjEyMzQ1Ng==

rv_parse_qradar

Разбирает значение в формате QRadar, включая необязательный заголовок syslog.

Спецификация функции

rv_parse_qradar(значение: <строка>)
:: <объект>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строковое представление сообщения QRadar

да

Ошибки

Функция rv_parse_qradar может возвращать ошибки, для которых требуется обработка:

  • значение закодировано не в UTF-8;

  • значение содержит ключ без соответствующего значения.

Примеры

Разбор сообщения без заголовка syslog и со вложенным полем Message

Example 75. Исходный код
rv_parse_msgpack!("AgentDevice=WindowsLog\tAgentLogFile=Security\tPluginVersion=7.2.9.105\tSource=Microsoft-Windows-Security-Auditing\tComputer=dc04.lab2012.local\tOriginatingComputer=192.0.2.0\tUser=\tDomain=\tEventID=4624\tEventIDCode=4624\tEventType=8\tEventCategory=12544\tRecordNumber=11103971\tTimeGenerated=1610705793\tTimeWritten=1610705793\tLevel=Log Always\tKeywords=Audit Success\tTask=SE_ADT_LOGON_LOGON\tOpcode=Info\tMessage=Вход с учетной записью выполнен успешно.  Субъект:  ИД безопасности:  NULL SID  Имя учетной записи:  -  Домен учетной записи:  -  Код входа:  0x0  Тип входа:   3  Уровень олицетворения:  Делегирование  Новый вход:  ИД безопасности:  NT AUTHORITY\\СИСТЕМА  Имя учетной записи:  USER  Домен учетной записи:  LAB2012  Код входа:  0x1E6112B9  GUID входа:  {06457096-03A4-55FB-28EA-9882B565E681}  Сведения о процессе:  Идентификатор процесса:  0x0  Имя процесса:  -  Сведения о сети:  Имя рабочей станции: -  Сетевой адрес источника: fe80::7830:1b00:4e5f:1300  Порт источника:  51755  Данное событие возникает при создании сеанса входа.\n".as_bytes())
Example 76. Результат
{
    "AgentDevice": "WindowsLog",
    "AgentLogFile": "Security",
    "PluginVersion": "7.2.9.105",
    "Source": "Microsoft-Windows-Security-Auditing",
    "Computer": "dc04.lab2012.local",
    "OriginatingComputer": "192.0.2.0"
    "User": ""
    "Domain": ""
    "EventID": "4624"
    "EventIDCode": "4624"
    "EventType": "8"
    "EventCategory": "12544"
    "RecordNumber": "11103971"
    "TimeGenerated": "1610705793"
    "TimeWritten": "1610705793"
    "Level": "Log Always"
    "Keywords": "Audit Success"
    "Task": "SE_ADT_LOGON_LOGON"
    "Opcode": "Info"
    "Message": {
        "Вход с учетной записью выполнен успешно.": "",
        "Субъект": "ИД безопасности: NULL SID",
        "Имя учетной записи": "-",
        "Домен учетной записи": "-",
        "Код входа": "0x0",
        "Тип входа": "3",
        "Уровень олицетворения": "Делегирование",
        "Новый вход": {
            "ИД безопасности": "NT AUTHORITY\\СИСТЕМА",
            "Имя учетной записи": "USER",
            "Домен учетной записи": "LAB2012",
            "Код входа": "0x1E6112B9",
            "GUID входа": "{06457096-03A4-55FB-28EA-9882B565E681}"
        },
        "Сведения о процессе": {
            "Идентификатор процесса": "0x0",
            "Имя процесса": "-"
        },
        "Сведения о сети": {
            "Имя рабочей станции": "-",
            "Сетевой адрес источника": "2001:DB8::7830:1b00:4e5f:1300",
            "Порт источника": "51755"
        }
    }
}

Разбор сообщения c заголовком syslog

Example 77. Исходный код
rv_parse_msgpack!("<13>Jan 15 13:16:35 DC04  AgentDevice=WindowsLog\tAgentLogFile=Security\tPluginVersion=7.2.9.105\tSource=Microsoft-Windows-Security-Auditing\tComputer=dc04.lab2012.local\tOriginatingComputer=192.0.2.0\tUser=\tDomain=\tEventID=4624\tEventIDCode=4624\tEventType=8\tEventCategory=12544\tRecordNumber=11103971\tTimeGenerated=1610705793\tTimeWritten=1610705793\tLevel=Log Always\tKeywords=Audit Success\tTask=SE_ADT_LOGON_LOGON\tOpcode=Info\n".as_bytes())
Example 78. Результат
{
    "syslog_facility": "1",
    "syslog_priority": "13",
    "syslog_severity": "5",
    "at": "Jan 15 13:16:35",
    "ahost": "DC04",
    "AgentDevice": "WindowsLog",
    "AgentLogFile": "Security",
    "PluginVersion": "7.2.9.105",
    "Source": "Microsoft-Windows-Security-Auditing",
    "Computer": "dc04.lab2012.local",
    "OriginatingComputer": "192.0.2.0"
    "User": ""
    "Domain": ""
    "EventID": "4624"
    "EventIDCode": "4624"
    "EventType": "8"
    "EventCategory": "12544"
    "RecordNumber": "11103971"
    "TimeGenerated": "1610705793"
    "TimeWritten": "1610705793"
    "Level": "Log Always"
    "Keywords": "Audit Success"
    "Task": "SE_ADT_LOGON_LOGON"
    "Opcode": "Info"
}

parse_syslog

Разбирает значение в формате syslog.

Спецификация функции

parse_syslog(значение: <строка>)
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Текст, содержащий сообщение syslog для разбора.

да

Примечания

Эта функция имеет особое поведение, о котором следует знать.

  • Функция разбирает различные форматы syslog. Это включает RFC 6587, RFC 5424, RFC 3164 и другие распространенные варианты (например, стиль syslog в Nginx).

  • Все значения возвращаются как строки. Рекомендуется вручную преобразовывать значения в нужные типы.

Ошибки

Функция parse_syslog может возвращать ошибки, для которых требуется обработка:

  • значение не является правильно отформатированным сообщением syslog.

Примеры

Разбор журнала Syslog (5424)

Example 79. Исходный код
parse_syslog!(
s'<13>1 2020-03-13T20:45:38.119Z dynamicwireless.name non 2426 ID931 [exampleSDID@32473 iut="3" eventSource= "Application" eventID="1011"] Try to override the THX port, maybe it will reboot the neural interface!'
)
Example 80. Результат
{
"severity": "notice",
"facility": "user",
"timestamp": "2020-03-13T20:45:38.119Z",
"hostname": "dynamicwireless.name",
"appname": "non",
"procid": 2426,
"msgid": "ID931",
"message": "Try to override the THX port, maybe it will reboot the neural interface!",
"exampleSDID@32473": {
"eventID": "1011",
"eventSource": "Application",
"iut": "3"
},
"version": 1
}

Функции преобразования кодов и параметров Syslog

to_syslog_facility

Преобразует value, код устройства Syslog, в соответствующее ему ключевое слово Syslog. т.е. 0 в "kern", 1 в "user" и т.д.

Спецификация функции

to_syslog_facility(значение: <целое число>)
:: <строка> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

целое число

Код устройства.

да

Ошибки

Функция to_syslog_facility может возвращать ошибки, для которых требуется обработка:

  • value не является допустимым кодом устройства Syslog.

Примеры

Приведение к устройству Syslog

Example 81. Исходный код
to_syslog_facility!(4)
Example 82. Результат
auth

to_syslog_level

Преобразует value, код уровня серьезности Syslog, в соответствующее ключевое слово, например, 0 в "emerg", 1 в "alert" и т. д.

Спецификация функции

to_syslog_level(значение: <целое число>)
:: <строка> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

целое число

Код уровня серьезности.

да

Ошибки

Функция to_syslog_level может возвращать ошибки, для которых требуется обработка:

  • value не является допустимым кодом уровня серьезности Syslog.

Примеры

Приведение к уровню Syslog

Example 83. Исходный код
to_syslog_level!(5)
Example 84. Результат
notice

to_syslog_severity

Преобразует value, ключевое слово уровня Syslog, в целое число уровня серьезности Syslog (0 до 7).

Спецификация функции

to_syslog_severity(значение: <строка>)
:: <целое число> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Ключевое слово уровня Syslog для преобразования.

да

Ошибки

Функция to_syslog_severity может возвращать ошибки, для которых требуется обработка:

  • value не является допустимым ключевым словом уровня Syslog.

Примеры

Приведение к уровню серьезности Syslog

Example 85. Исходный код
to_syslog_severity!("alert")
Example 86. Результат
1

Функции разбора структурированных данных

parse_csv

Разбирает отдельную строку в формате CSV. Если входное значение состоит из нескольких строк, будет проанализирована только первая строка.

Спецификация функции

parse_csv(значение: <строка>, [delimiter: <строка>])
:: <массив> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для разбора.

да

delimiter

строка

Разделитель полей для использования при разборе. Должен быть однобайтовым символом UTF-8.

,

нет

Примечания

У этой функции есть специальное поведение, которое следует учитывать:

  • Все значения возвращаются в виде строк. Рекомендуется вручную приводить значения к желаемым типам при необходимости.

Ошибки

Функция parse_csv может возвращать ошибки, для которых требуется обработка:

  • Разделитель не является однобайтовым символом UTF-8.

  • значение не является допустимой строкой CSV.

Примеры

Разбор отдельной строки в формате CSV

Example 87. Исходный код
parse_csv!("foo,bar,\"foo \"\", bar\"")
Example 88. Результат
[ "foo", "bar", "foo \", bar"]

Разбор отдельной строки в формате CSV с пользовательским разделителем

Example 89. Исходный код
parse_csv!("foo bar", delimiter: " ")
Example 90. Результат
[ "foo", "bar"]

rv_parse_html

Разбирает значение в формате HTML.

Спецификация функции

rv_parse_html(значение: <строка>, [trim: <логическое значение>, attr_prefix: <строка>, text_key: <строка>, always_use_text_key: <логическое значение>, parse_bool: <логическое значение>, parse_null: <логическое значение>, parse_number: <логическое значение>])
:: <объект>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

HTML-документ в виде строки.

да

trim

логическое значение

Удалять пробелы вокруг элементов HTML.

true

нет

include_attr

логическое значение

Включать атрибуты HTML в возвращаемый объект.

true

нет

attr_prefix

строка

Префикс строки для ключей атрибутов HTML.

"@"

нет

text_key

строка

Ключ, под которым возвращается содержимое элементов HTML.

"text"

нет

always_use_text_key

логическое значение

Всегда возвращать содержимое элементов HTML под ключом, указанным в параметре text_key. Если true, содержимое будет сохраняться под отдельным ключом, даже если у элемента нет атрибутов.

false

нет

parse_bool

логическое значение

Интерпретировать строки "true" и "false" как логические значения.

true

нет

parse_null

логическое значение

Интерпретировать пустые строки и строки "null" как пустые значения.

true

нет

parse_number

логическое значение

Интерпретировать строковые представления чисел ("1") как числовые типы.

true

нет

Ошибки

Функция rv_parse_html может возвращать ошибки, для которых требуется обработка:

  • значение не является корректным документом HTML.

Примеры

С указанием text_key, без разбора числовых типов

Example 91. Исходный код
value = r"<book category="PROGRAMMING"> <title lang="en">The Rust programming language</title> <author>Steve Klabnik, Carol Nichols</author> <year>2019</year></book>"
rv_parse_html!(value, text_key: "value", parse_number: false)
Example 92. Результат
{ "book":
{ "@category": "PROGRAMMING",
"author": "Steve Klabnik, Carol Nichols",
"title":
{ "@lang": "en",
"value": "The Rust programming language"
},
"year": "2019"
}
}

С использованием text_key во всех случаях

Example 93. Исходный код
value = r#"<b>test</b>"#
rv_parse_html!(value, text_key: "value", text_key: "node", always_use_text_key: true)
Example 94. Результат
{ "b": { "node": "test" } }

Без удаления пробелов между элементами

Example 95. Исходный код
value = r#"<root>  <a>test</a>  </root>#
rv_parse_html!(value, trim: false)
Example 96. Результат
{
    "root": {
        "a": "test",
        "text": ["  ", "  "],
    }
}

parse_json

Разбирает значение как JSON.

Чтобы извлечь содержимое из повреждённого JSON, используйте функцию rv_json_extract_payload.

Спецификация функции

parse_json(значение: <строка>, [max_depth: <целое число>])
:: <логическое значение | целое число | число с плавающей точкой | строка | объект | массив | пустое значение> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка с представлением JSON для разбора.

да

max_depth

целое число

Количество уровней для разбора вложенных JSON-документов. Значение должно быть в диапазоне от 1 до 128.

нет

Примечания

У этой функции есть специальное поведение, которое следует учитывать:

  • Возвращаются только типы JSON. Если нужно преобразовать string в timestamp, используйте функцию parse_timestamp.

Ошибки

Функция parse_json может возвращать ошибки, для которых требуется обработка:

  • значение не является допустимым JSON-представлением

Примеры

Разбор JSON

Example 97. Исходный код
parse_json!("{\"key\": \"val\"}")
Example 98. Результат
{
"key": "val"
}

Разбор JSON с ограничением глубины

Example 99. Исходный код
parse_json!("{\"top_level\":{\"key\": \"val\"}}", max_depth: 1)
Example 100. Результат
{
"top_level": "{\"key\": \"val\"}"
}

rv_json_extract_payload

Извлекает значение ключа payload_key из повреждённого или невалидного JSON. Е

Спецификация функции

rv_json_extract_payload(значение: <строка>, payload_key: <строка>)
:: <логическое значение | целое число | число с плавающей точкой | строка | объект | массив | пустое значение>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка с представлением JSON для извлечения

да

payload_key

строка

Ключ, значение которого нужно извлечь

да

Примечания

Особенность функции, о которой нужно знать:

  • Если указанный ключ встречается несколько раз, то будет извлечено значение только первого вхождения.

Ошибки

Функция rv_json_extract_payload может возвращать ошибки, для которых требуется обработка:

  • Значение не содержит ключ payload_key.

Примеры

JSON с валидной структурой:

Example 101. Исходный код
rv_json_extract_payload(s'{"a": 123, "payload"    : "data"}', payload_key: "payload")
Example 102. Результат
"data"

JSON с невалидной структурой:

Example 103. Исходный код
rv_json_extract_payload(s'"asd":123,"payload" : "text"', payload_key: "payload")
Example 104. Результат
"text"

Несколько ключей payload_key:

Example 105. Исходный код
rv_json_extract_payload(s'{ asd":123,"payload" : "first", "payload": "second" }', payload_key: "payload")
Example 106. Результат
"first"

parse_key_value

Разбирает значение в формате "ключ — значение", также известном как logfmt.

  • Ключи и значения могут быть заключены в кавычки ".

  • Символы " могут быть экранированы с помощью обратной косой черты \.

Спецификация функции

parse_key_value(значение: <строка>, [key_value_delimiter: <строка>, field_delimiter: <строка>, whitespace: <строка>, accept_standalone_key: <логическое значение>])
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для разбора.

да

key_value_delimiter

строка

Строка, разделяющая ключ и значение.

=

нет

field_delimiter

строка

Строка, разделяющая каждую пару "ключ — значение".

(пробел)

нет

whitespace

строка

Обработка пробелов вокруг разделителя, заданного в параметре key_value_delimiter:

  • lenient — игнорировать пробелы;

  • strict — интерпретировать пробелы как обычные символы. *

lenient

нет

accept_standalone_key

логическое значение

Разрешены ли ключи без значений. Если такие ключи разрешены, в возвращаемом объекте им будет присвоено значение true.

true

нет

Примечания

У этой функции есть специальное поведение, которое следует учитывать:

  • Все значения возвращаются в виде строк или в виде массива строк для дублирующихся ключей. Рекомендуется вручную преобразовывать значения в желаемые типы.

Ошибки

Функция parse_key_value может возвращать ошибки, для которых требуется обработка:

  • значение не является правильно отформатированной строкой "ключ — значение".

Примеры

Разбор лога в формате logfmt

Example 107. Исходный код
parse_key_value!(
"@timestamp=\"Sun Jan 10 16:47:39 EST 2021\" level=info msg=\"Stopping all fetchers\" tag#production=stopping_fetchers id=ConsumerFetcherManager-1382721708341 module=kafka.consumer.ConsumerFetcherManager"
)
Example 108. Результат
{
"@timestamp": "Sun Jan 10 16:47:39 EST 2021",
"level": "info",
"msg": "Stopping all fetchers",
"tag#production": "stopping_fetchers",
"id": "ConsumerFetcherManager-1382721708341",
"module": "kafka.consumer.ConsumerFetcherManager"
}

Разбор лога с разделителем запятой

Example 109. Исходный код
parse_key_value!(
"path:\"/cart_link\", host:store.app.com, fwd: \"102.30.171.16\", dyno: web.1, connect:0ms, service:87ms, status:304, bytes:632, protocol:https",
field_delimiter: ",",
key_value_delimiter: ":"
)
Example 110. Результат
{
"path": "/cart_link",
"host": "store.app.com",
"fwd": "102.30.171.16",
"dyno": "web.1",
"connect": "0ms",
"service": "87ms",
"status": "304",
"bytes": "632",
"protocol": "https"
}

Разбор журнала с ключами без значений

Example 111. Исходный код
parse_key_value!(
"env:prod,service:backend,region:eu-east1,beta",
field_delimiter: ",",
key_value_delimiter: ":",
)
Example 112. Результат
{
"env": "prod",
"service": "backend",
"region": "eu-east1",
"beta": true
}

Разбор дублирующихся ключей

Example 113. Исходный код
parse_key_value!(
"at=info,method=GET,path=\"/index\",status=200,tags=dev,tags=dummy",
field_delimiter: ",",
key_value_delimiter: "=",
)
Example 114. Результат
{
"at": "info",
"method": "GET",
"path": "/index",
"status": "200",
"tags": [
"dev",
"dummy"
]
}

parse_ruby_hash

Разбирает значение как хэш Ruby.

Спецификация функции

parse_ruby_hash(значение: <строка>)
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строковое представление хэша Ruby для разбора

да

Примечания

Эта функция имеет особое поведение, о котором следует знать.

  • Возвращаются только типы Ruby. Если нужно преобразовать строку в метку времени, используйте функцию parse_timestamp.

Ошибки

Функция parse_ruby_hash может возвращать ошибки, для которых требуется обработка:

  • значение не является допустимым представлением хэша Ruby.

Примеры

Разбор хэша Ruby

Example 115. Исходный код
parse_ruby_hash!(s'{ "test" => "value", "testNum" => 0.2, "testObj" => { "testBool" => true, "testNull" => nil } }')
Example 116. Результат
{
"test": "value",
"testNum": 0.2,
"testObj": {
"testBool": true,
"testNull": null
}
}

parse_xml

Разбирает значение как XML.

Спецификация функции

parse_xml(значение: <строка>, [include_attr: <логическое значение>, attr_prefix: <строка>, text_key: <строка>, always_use_text_key: <логическое значение>, parse_bool: <логическое значение>, parse_null: <логическое значение>, parse_number: <логическое значение>])
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строковое представление XML-документа для разбора.

да

include_attr

логическое значение

Включать атрибуты XML-тегов в возвращаемый объект.

true

нет

attr_prefix

строка

Префикс строки для ключей атрибутов XML-тегов.

@

нет

text_key

строка

Имя ключа для расширенных текстовых узлов.

text

нет

always_use_text_key

логическое значение

Всегда возвращать узлы текста как {"<text_key>": "value"}.

false

нет

parse_bool

логическое значение

Разбирать "true" и "false" как логические значения.

true

нет

parse_null

логическое значение

Разбирать "null" как null.

true

нет

parse_number

логическое значение

Разбирать числа как целые/вещественные.

true

нет

Примечания

Эта функция имеет особое поведение, о котором следует знать.

  • Допустимый XML должен содержать ровно один корневой узел. Всегда возвращает объект.

Ошибки

Функция parse_xml может возвращать ошибки, для которых требуется обработка:

  • значение не является правильным XML-документом

Примеры

Разбор XML

Example 117. Исходный код
value = s'<book category="CHILDREN"><title lang="en">Harry Potter</title><author>J K. Rowling</author><year>2005</year></book>';


parse_xml!(value, text_key: "value", parse_number: false)
Example 118. Результат
{
"book": {
"@category": "CHILDREN",
"author": "J K. Rowling",
"title": {
"@lang": "en",
"value": "Harry Potter"
},
"year": "2005"
}
}

Функции разбора метаданных и параметров

parse_duration

Разбирает значение в удобочитаемый формат длительности, используя единицы, указанные в параметре unit.

Спецификация функции

parse_duration(значение: <строка>, unit: <строка>)
:: <число с плавающей точкой> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка с длительностью.

да

unit

строка

Единица измерения для вывода длительности:

  • ns — наносекунды;

  • us, µs — микросекунды;

  • ms — миллисекунды;

  • cs — сантисекунды;

  • ds — децисекунды;

  • s — секунды;

  • m — минуты;

  • h — часы;

  • d — сутки.

да

Ошибки

Функция parse_duration может возвращать ошибки, для которых требуется обработка:

  • значение не имеет правильного формата длительности

Примеры

Разбор длительности (миллисекунды)

Example 119. Исходный код
parse_duration!("1005ms", unit: "s")
Example 120. Результат
1.005

parse_query_string

Разбирает значение как строку запроса (query string).

Спецификация функции

parse_query_string(значение: <строка>)
:: <объект>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для разбора.

да

Примечания

Эта функция имеет особое поведение, о котором следует знать.

  • Все значения возвращаются как строки. Рекомендуется вручную преобразовывать значения в нужные типы. Пустые ключи и значения разрешены.

Примеры

Разбор строки запроса

Example 121. Исходный код
parse_query_string("foo=%2B1&bar=2&bar=3&xyz")
Example 122. Результат
{
"foo": "+1",
"bar": [
"2",
"3"
],
"xyz": ""
}

Разбор строки запроса Ruby on Rails

Example 123. Исходный код
parse_query_string("?foo%5b%5d=1&foo%5b%5d=2")
Example 124. Результат
{
"foo[]": [
"1",
"2"
]
}

parse_tokens

Разбирает значение в формате "token". Токенами считаются такие последовательности символов:

  • Слова, окруженные пробелами.

  • Тексты, заключенные в двойные кавычки: "..". Кавычки можно включить в токен, если они экранированы обратной косой чертой (\).

  • Тексты, заключенные в квадратные скобки: [..]. Закрывающие квадратные скобки можно включить в токен, если они экранированы обратной косой чертой (\).

Спецификация функции

parse_tokens(значение: <строка>)
:: <массив> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для токенизации.

да

Примечания

Эта функция имеет особое поведение, о котором следует знать.

  • Все значения токенов возвращаются как строки. Рекомендуется вручную преобразовывать значения в нужные типы.

Ошибки

Функция parse_tokens может возвращать ошибки, для которых требуется обработка:

  • значение не является правильно отформатированной строкой с токенами.

Примеры

Разбор токенов

Example 125. Исходный код
parse_tokens(
"A sentence \"with \\\"a\\\" sentence inside\" and [some brackets]"
)
Example 126. Результат
[
"A",
"sentence",
"with \\\"a\\\" sentence inside",
"and",
"some brackets"
]

parse_url

Разбирает значение в формате URL.

Спецификация функции

parse_url(значение: <строка>, [default_known_ports: <логическое значение>])
:: <объект> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Текст URL.

да

default_known_ports

логическое значение

Заполнять ли номер порта значением по умолчанию. Если во входном URL не указан номер порта или он совпадает со стандартным, поле будет заполнено значением по умолчанию. Это применимо к протоколам http, https, ftp, ws и wss.

false

нет

Примечания

Особенности функции, о которых нужно знать:

  • По умолчанию, если во входном URL указан стандартный порт, он не учитывается. Поле port в возвращаемом объекте остаётся пустым.

Ошибки

Функция parse_url может возвращать ошибки, для которых требуется обработка:

  • значение не является правильно отформатированным URL.

Примеры

Разбор URL

Example 127. Исходный код
parse_url!("ftp://foo:bar@example.com:4343/foobar?hello=world#123")
Example 128. Результат
{
"scheme": "ftp",
"username": "foo",
"password": "bar",
"host": "example.com",
"port": 4343,
"path": "/foobar",
"query": {
"hello": "world"
},
"fragment": "123"
}

Разбор URL с портом по умолчанию

Example 129. Исходный код
parse_url!("https://example.com", default_known_ports: true)
Example 130. Результат
{
"scheme": "https",
"username": "",
"password": "",
"host": "example.com",
"port": 443,
"path": "/",
"query": {},
"fragment": null
}

parse_user_agent

Разбирает значение как строку пользовательского агента. Формат пользовательского агента имеет нечеткое определение, поэтому функция обеспечивает лишь максимально возможные результаты, а не точный разбор.

Спецификация функции

parse_user_agent(значение: <строка>, [mode: <строка>])
:: <объект>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Строка для разбора.

да

mode

строка

Определяет характеристики производительности и надежности:

  • fast — самый быстрый, но менее надежный режим. Используется синтаксический анализатор из проекта Woothee.

  • reliable — обеспечивает большую надежность, чем режим fast, и в большинстве случаев не снижает скорость работы. Используется синтаксический анализатор Wood These. Если Wood These не разобрал какие-либо поля, используется анализатор uapproject.

  • enriched — объединяет результаты Wood These и uapproject.

fast

нет

Примечания

Эта функция имеет особое поведение, о котором следует знать:

  • Все значения возвращаются как строки или как null. Рекомендуется вручную преобразовывать значения в нужные типы.

  • Разные режимы возвращают разные схемы.

  • Поля, которые не были разобраны, устанавливаются как null.

Примеры

Быстрый режим

Example 131. Исходный код
parse_user_agent(
"Mozilla Firefox 1.0.1 Mozilla/5.0 (X11; U; Linux i686; de-DE; rv:1.7.6) Gecko/20050223 Firefox/1.0.1"
)
Example 132. Результат
{
"browser": {
"family": "Firefox",
"version": "1.0.1"
},
"device": {
"category": "pc"
},
"os": {
"family": "Linux",
"version": null
}
}

Надежный режим

Example 133. Исходный код
parse_user_agent(
"Mozilla/4.0 (compatible; MSIE 7.66; Windows NT 5.1; SV1; .NET CLR 1.1.4322)",
mode: "reliable"
)
Example 134. Результат
{
"browser": {
"family": "Internet Explorer",
"version": "7.66"
},
"device": {
"category": "pc"
},
"os": {
"family": "Windows XP",
"version": "NT 5.1"
}
}

Расширенный режим

Example 135. Исходный код
parse_user_agent(
"Opera/9.80 (J2ME/MIDP; Opera Mini/4.3.24214; iPhone; CPU iPhone OS 4_2_1 like Mac OS X; AppleWebKit/24.783; U; en) Presto/2.5.25 Version/10.54",
mode: "enriched"
)
Example 136. Результат
{
"browser": {
"family": "Opera Mini",
"major": "4",
"minor": "3",
"patch": "24214",
"version": "10.54"
},
"device": {
"brand": "Apple",
"category": "smartphone",
"family": "iPhone",
"model": "iPhone"
},
"os": {
"family": "iOS",
"major": "4",
"minor": "2",
"patch": "1",
"patch_minor": null,
"version": "4.2.1"
}
}

Функции преобразования IP

ip_aton

Преобразует IPv4-адрес в представлении чисел и точек в байты, представленные в сетевом порядке, как целое число.

Функция повторяет поведение функции inet_aton.

Спецификация функции

ip_aton(значение: <строка>)
:: <целое число> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

IP-адрес для преобразования в бинарный формат.

да

Ошибки

Функция ip_aton может возвращать ошибки, для которых требуется обработка:

  • значение не является допустимым IPv4-адресом.

Примеры

IPv4 в целое число

Example 137. Исходный код
ip_aton!("1.2.3.4")
Example 138. Результат
16909060

ip_cidr_contains

Определяет, содержится ли ip в блоке, заданном с помощью cidr.

Спецификация функции

ip_cidr_contains(cidr: <строка>, ip: <строка>)
:: <логическое значение> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

cidr

строка

Маска CIDR (v4 или v6).

да

ip

строка

IP-адрес (v4 или v6).

да

Ошибки

Функция ip_cidr_contains может возвращать ошибки, для которых требуется обработка:

  • cidr не является допустимой маской CIDR.

  • ip не является допустимым IP-адресом.

Примеры

IPv4 содержит CIDR

Example 139. Исходный код
ip_cidr_contains!("192.168.0.0/16", "192.168.10.32")
Example 140. Результат
true

IPv6 содержит CIDR

Example 141. Исходный код
ip_cidr_contains!("2001:4f8:4:ba::/64", "2001:4f8:4:ba:2e0:81ff:fe22:d1f1")
Example 142. Результат
true

ip_ntoa

Преобразует числовое представление IPv4-адреса в байтах, представленных в сетевом порядке, в представление чисел и точек.

Функция повторяет поведение функции inet_ntoa.

Спецификация функции

ip_ntoa(значение: <строка>)
:: <строка> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Целочисленное представление IPv4-адреса.

да

Ошибки

Функция ip_ntoa может возвращать ошибки, для которых требуется обработка:

  • значение не может быть представлено в u32.

Примеры

Целое число в IPv4

Example 143. Исходный код
ip_ntoa!(16909060)
Example 144. Результат
1.2.3.4

ip_ntop

Преобразует IPv4 и IPv6-адреса из бинарной формы в текстовую форму.

Функция повторяет поведение функции inet_ntop.

Спецификация функции

ip_ntop(значение: <строка>)
:: <строка> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

Двоичные данные для преобразования. Для IPv4-адресов длина должна быть 4 байта (32 бита). Для IPv6-адресов длина должна быть 16 байт (128 бит).

да

Примечания

Эта функция имеет особое поведение, о котором стоит знать.

  • Двоичные данные для этой функции не всегда легко отобразить в печатном виде. Однако результаты функций, таких как decode_base64 или decode_percent, все равно можно использовать корректно.

Ошибки

Функция ip_ntop может возвращать ошибки, для которых требуется обработка:

  • значение должен быть длиной 4 или 16 байт

Примеры

Преобразование IPv4-адреса из байтов после декодирования из Base64

Example 145. Исходный код
ip_ntop!(decode_base64!("wKgAAQ=="))
Example 146. Результат
192.168.0.1

Преобразование IPv6-адреса из байтов после декодирования из Base64

Example 147. Исходный код
ip_ntop!(decode_base64!("IAENuIWjAAAAAIouA3BzNA=="))
Example 148. Результат
2001:db8:85a3::8a2e:370:7334

ip_pton

Преобразует IPv4 и IPv6-адреса из текстовой формы в бинарную форму.

  • Бинарная форма IPv4-адресов имеет длину 4 байта (32 бита).

  • Бинарная форма IPv6-адресов имеет длину 16 байт (128 бит).

Функция повторяет поведение функции inet_pton.

Спецификация функции

ip_pton(значение: <строка>)
:: <строка> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

значение

строка

IP-адрес (v4 или v6) для преобразования в бинарную форму.

да

Примечания

Эта функция имеет особое поведение, о котором стоит знать.

  • Двоичные данные из этой функции не всегда могут быть удобочитаемыми. Однако результаты функций, таких как encode_base64 или encode_percent, всё равно можно корректно обрабатывать.

Ошибки

Функция ip_pton может возвращать ошибки, для которых требуется обработка:

  • значение не является допустимым IP-адресом (v4 или v6) в текстовой форме.

Примеры

Преобразование IPv4-адреса в байты и кодирование в Base64

Example 149. Исходный код
encode_base64(ip_pton!("192.168.0.1"))
Example 150. Результат
wKgAAQ==

Преобразование IPv6-адреса в байты и кодирование в Base64

Example 151. Исходный код
encode_base64(ip_pton!("2001:db8:85a3::8a2e:370:7334"))
Example 152. Результат
IAENuIWjAAAAAIouA3BzNA==

ip_subnet

Извлекает подсетевой адрес из ip с использованием заданной подсети.

Спецификация функции

ip_subnet(ip: <строка>, подсеть: <строка>)
:: <строка> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

ip

строка

IP-адрес (v4 или v6).

да

подсеть

строка

Подсеть, которую необходимо извлечь из IP-адреса. Это может быть либо длина префикса, например, /8, либо сетевая маска, например, 255.255.0.0. Сетевая маска может быть как IPv4, так и IPv6 адресом.

да

Примечания

Эта функция имеет особое поведение, о котором стоит знать.

  • Работает как с IPv4, так и с IPv6 адресами. Версия IP для маски должна быть такой же, как у предоставленного адреса.

Ошибки

Функция ip_subnet может возвращать ошибки, для которых требуется обработка:

  • ip не является допустимым IP-адресом.

  • подсеть не является допустимой подсетью.

Примеры

Подсеть IPv4

Example 153. Исходный код
ip_subnet!("192.168.10.32", "255.255.255.0")
Example 154. Результат
192.168.10.0

Подсеть IPv6

Example 155. Исходный код
ip_subnet!("2404:6800:4003:c02::64", "/32")
Example 156. Результат
2404:6800::

ip_to_ipv6

Преобразует ip в адрес IPv6.

Спецификация функции

ip_to_ipv6(ip: <строка>)
:: <строка> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

ip

строка

IP-адрес, который необходимо преобразовать в IPv6.

да

Ошибки

Функция ip_to_ipv6 может возвращать ошибки, для которых требуется обработка:

  • ip не является допустимым IP-адресом.

Примеры

IPv4 в IPv6

Example 157. Исходный код
ip_to_ipv6!("192.168.10.32")
Example 158. Результат
::ffff:192.168.10.32

ipv6_to_ipv4

Преобразует ip в адрес IPv4. Если ip уже является IPv4-адресом, то он возвращается без изменений. Если ip в данный момент является IPv6-адресом, то он должен быть совместим с IPv4, в противном случае возникнет ошибка.

Спецификация функции

ipv6_to_ipv4(ip: <строка>)
:: <строка> , <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

ip

строка

IPv4-совместимый IPv6-адрес для преобразования.

да

Ошибки

Функция ipv6_to_ipv4 может возвращать ошибки, для которых требуется обработка:

  • ip не является допустимым IP-адресом.

  • ip является IPv6-адресом, который не совместим с IPv4.

Примеры

IPv6 в IPv4

Example 159. Исходный код
ipv6_to_ipv4!("::ffff:192.168.0.1")
Example 160. Результат
192.168.0.1