Использование API VirusTotal

Использование API VirusTotal

Вы наверняка не раз пользовались услугами сайта онлайн проверки файлов virustotal.com, чтобы проверить, не содержат ли файлы вредоносных функций, либо протестировать собственные наработки.

У популярного сервиса есть бесплатный API, работу с которым на Python мы и рассмотрим в сегодняшней статье.

Сайт онлайн сканера virustotal.com
Сайт онлайн сканера virustotal.com

Чтобы использовать программный интерфейс VirusTotal без ограничений, нужно получить ключ, который обходится в не хилую сумму — цены стартуют с 700 евро в месяц. Причем частному лицу даже при готовности выложить такую сумму ключ не дадут.

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

API VirusTotal нельзя использовать в коммерческих продуктах или услугах и в проектах, которые могут нанести прямой либо косвенный ущерб антивирусной индустрии.

Получение ключа API Key VirusTotal

Итак, первым делом необходимо зарегистрироваться на сайте VirusTotal. Тут проблем никаких — я уверен, что вы справитесь. После регистрации ключ доступа можно найти выбрав пункт меню API key.

Вот здесь лежит ключ доступа к API VirusTotal
Вот здесь лежит ключ доступа к API VirusTotal

Версии API VirusTotal

На сегодняшний день актуальная версия API имеет номер 2. Но при этом уже существует и новый вариант — номер 3. Эта версия API пока еще находится в стадии официальной беты, но ее уже вполне можно использовать, тем более что возможности, которые она предоставляет, гораздо больше.

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

API VirusTotal. Версия 2

Как и в случае с другими популярными веб-сервисами, работа с API заключается в пересылке запросов по HTTP и получении ответов.

API второй версии позволяет:

  • отправлять файлы на проверку;
  • получать отчет по проверенным ранее файлам, с использованием идентификатора файла (SHA-256, SHA-1 или MD5-хеш файла либо значение scan_id из ответа, полученного после отправки файла);
  • отправлять URL для сканирования на сервер;
  • получать отчет по проверенным ранее адресам с использованием либо непосредственно URL, либо значения scan_id из ответа, полученного после отправки URL на сервер;
  • получать отчет по IP-адресу;
  • получать отчет по доменному имени.

Ошибки

Если запрос был правильно обработан и ошибок не возникло, будет возвращен код 200 (OK).

Если же произошла ошибка, то могут быть такие варианты:

  • 204 — ошибка типа Request rate limit exceeded. Возникает, когда превышена квота допустимого количества запросов (для бесплатного ключа квота составляет четыре запроса в минуту);
  • 400 — ошибка типа Bad request. Возникает, когда некорректно сформирован запрос, например если нет нужных аргументов или у них недопустимые значения;
  • 403 — ошибка типа Forbidden. Возникает, если пытаться использовать функции API, доступные только с платным ключом, когда его нет.

Еще по теме: Как хакеры скрывают вирусы в документах Office

При правильном формировании запроса (код состояния HTTP — 200) ответ будет представлять собой объект JSON, в теле которого присутствуют как минимум два поля:

  • response_code — если запрашиваемый объект (файл, URL, IP-адрес или имя домена) есть в базе VirusTotal (то есть проверялся раньше) и информация об этом объекте может быть получена, то значение этого поля будет равно единице; если запрашиваемый объект находится в очереди на анализ, значение поля будет -2; если запрашиваемый объект отсутствует в базе VirusTotal — равно нулю;
  • verbose_msg предоставляет более подробное описание значения response_code (например, Scan finished, information embedded после отправки файла на сканирование).

Остальная информация, содержащаяся в ответном объекте JSON, зависит от того, какая функция API была использована.

Отправка файла на сервер для сканирования

Для отправки файла на сканирование необходимо сформировать POST-запрос на адрес https://www.virustotal.com/vtapi/v2, при этом в запросе нужно указать ключ доступа к API и передать сам файл (в этом случае существует ограничение на размер файла — не более 32 Мб). Это может выглядеть следующим образом (используем Python):

Здесь вместо строки <ключ доступа> необходимо вставить свой ключ доступа к API, а вместо <путь к файлу> — путь к файлу, который вы будете отправлять в VirusTotal. Если у вас нет библиотеки requests, то поставьте ее командой pip install requests.

В ответ, если все прошло успешно и код состояния HTTP равен 200, мы получим примерно следующую картину:

Здесь мы видим значения response_code и verbose_msg, а также хеши файла SHA-256, SHA-1 и MD5, ссылку на результаты сканирования файла на сайте permalink и идентификатор файла scan_id.

В приведенных в статье примерах кода опущена обработка ошибок. Помните, что в ходе открытия файла или отправки запросов на сервер могут возникать исключения: FileNotFoundError, если файла нет, requests.ConnectionError, requests.Timeout при ошибках соединения и так далее.

Получение отчета о последнем сканировании файла

Используя какой-либо из хешей или значение scan_id из ответа, можно получить отчет по последнему сканированию файла (если файл уже загружался на VirusTotal). Для этого необходимо сформировать GET-запрос и в запросе указать ключ доступа и идентификатор файла. Например, если у нас есть scan_id из предыдущего примера, то запрос будет выглядеть следующим образом:

В случае успеха в ответ мы увидим следующее:

Здесь, как и в предыдущем примере, получаем значения хешей файла, scan_id, permalink, значения response_code и verbose_msg. Также видим результаты сканирования файла антивирусами и общие результаты оценки total — сколько всего антивирусных движков было задействовано в проверке и positives — сколько антивирусов дали положительный вердикт.

Чтобы вывести результаты сканирования всеми антивирусами в удобоваримом виде, можно, например, написать что-то в таком роде:

Вывод на экран информации о результатах сканирования файла на VirusTotal с использованием разных антивирусных движков
Вывод на экран информации о результатах сканирования файла на VirusTotal с использованием разных антивирусных движков

Отправка URL на сервер для сканирования

Чтобы отправить URL для сканирования, нам нужно сформировать и послать POST-запрос, содержащий ключ доступа и сам URL:

В ответ мы получим примерно то же, что и при отправке файла, за исключением значений хеша. Содержимое поля scan_id можно использовать для получения отчета о сканировании данного URL.

Получение отчета о результатах сканирования URL-адреса

Сформируем GET-запрос с ключом доступа и укажем либо непосредственно сам URL в виде строки, либо значение scan_id, полученное с помощью предыдущей функции. Это будет выглядеть следующим образом:

Помимо ключа доступа и строки с URL, здесь присутствует опциональный параметр scan — по умолчанию он равен нулю. Если же его значение равно единице, то, когда информации о запрашиваемом URL в базе VirusTotal нет (URL ранее не проверялся), этот URL будет автоматически отправлен на сервер для проверки, после чего в ответ мы получим ту же информацию, что и при отправке URL на сервер. Если этот параметр равен нулю (или не задавался), мы получим отчет об этом URL либо (если информация о нем в базе VirusTotal отсутствует) ответ такого вида:

Получение информации об IP-адресах и доменах

Чтобы проверить IP-адреса и домены, нужно сформировать и отправить GET-запрос с ключом, именем проверяемого домена либо IP в виде строки. Для проверки домена это выглядит так:

Для проверки IP-адреса:

Ответы на такие запросы объемны и содержат много информации.

API VirusTotal. Версия 3

В третьей версии API намного гораздо больше возможностей по сравнению со второй — даже с использованием бесплатного ключа. Более того, при экспериментах с третьей версией я не заметил, чтобы ограничивалось число загружаемых объектов (файлов или адресов) на сервер в течение минуты. Похоже, ограничения бету пока вообще не касаются.

Функции третьей версии API спроектированы с использованием принципов REST и просты для понимания. Ключ доступа здесь передается в заголовке запроса.

Ошибки

В третьей версии API список ошибок (и, соответственно, кодов состояния HTTP) расширился. Были добавлены:

  • 401 — ошибка типа User Not Active Error, она возникает, когда учетная запись пользователя неактивна;
  • 401 — ошибка типа Wrong Credentials Error, возникает, если в запросе использован неверный ключ доступа;
  • 404 Not Found Error возникает, когда запрашиваемый объект анализа не найден;
  • 409 — ошибка типа Already Exists Error, возникает, когда ресурс уже существует;
  • 429 — ошибка типа Quota Exceeded Error, возникает при превышении одной из квот на число запросов (минутной, ежедневной или ежемесячной). Как я уже говорил, во время моих экспериментов никаких ограничений по количеству запросов в минуту не наблюдалось, хотя я использовал бесплатный ключ;
  • 429 — ошибка типа Too Many Requests Error, возникает при большом числе запросов за короткое время (может быть вызвана загруженностью сервера);
  • 503 — ошибка типа Transient Error, временная ошибка сервера, при которой повторная попытка запроса может сработать.

В случае ошибки, помимо кода состояния, сервер возвращает дополнительную информацию в форме JSON. Правда, как выяснилось, не для всех кодов состояния HTTP: к примеру, для ошибки 404 дополнительная информация представляет собой обычную строку.

Формат JSON для ошибки следующий:

Функции работы с файлами

Третья версия API позволяет:

  • загрузить файлы для анализа на сервер;
  • получить URL для загрузки на сервер файла размером больше 32 Мбайт;
  • получить отчеты о результатах анализа файлов;
  • повторно проанализировать файл;
  • получить комментарии пользователей VirusTotal к нужному файлу;
  • отправить свой комментарий к определенному файлу;
  • посмотреть результаты голосования по определенному файлу;
  • проголосовать за файл;
  • получить расширенную информацию о файле.

Для загрузки файла на сервер нужно его отправить через POST-запрос. Это можно сделать так:

В ответ мы получим следующее:

Здесь мы видим значение id, которое служит идентификатором файла. Этот идентификатор нужно использовать для получения информации об анализе файла в GET-запросах типа /analyses (об этом мы поговорим чуть позже).

Чтобы получить URL для загрузки большого файла (более 32 Мбайт), нужно отправить GET-запрос, в котором в качестве URL указывается https://www.virustotal.com/api/v3/files/upload_url. В заголовок вставляем ключ доступа:

В ответ получим JSON с адресом, по которому следует загрузить файл для анализа. Полученный URL при этом можно использовать только один раз.

Чтобы получить информацию о файле, который сервис уже анализировал, нужно сделать GET-запрос с идентификатором файла в URL (им может быть хеш SHA-256, SHA-1 или MD5). Так же как и в предыдущих случаях, указываем в заголовке ключ доступа:

В ответ мы получим отчет о проверке файла, где, помимо результатов сканирования всеми антивирусами VirusTotal, будет много дополнительной информации, состав которой зависит от типа проверенного файла. Например, для исполняемых файлов можно увидеть информацию о таких атрибутах:

Или, например, информацию о секциях исполняемого файла:

Если файл ранее не загружался на сервер и еще не анализировался, то в ответ мы получим ошибку типа Not Found Error с HTTP-кодом состояния, равным 404:

Чтобы повторно проанализировать файл, нужно также отправить на сервер GET-запрос, в котором в URL помещаем идентификатор файла, а в конце добавляем /analyse:

Ответ будет включать в себя такой же дескриптор файла, как и в первом случае — при загрузке файла на сервер. И так же, как и в первом случае, идентификатор из дескриптора можно использовать для получения информации об анализе файла через GET-запрос типа /analyses.

Просмотреть комментарии пользователей сервиса, а также результаты голосования по файлу можно, отправив на сервер соответствующий GET-запрос. Для получения комментариев:

Для получения результатов голосования:

В обоих случаях можно использовать дополнительный параметр limit, определяющий максимальное количество комментариев или голосов в ответе на запрос. Использовать этот параметр можно, например, так:

Чтобы разместить свой комментарий или проголосовать за файл, создаем POST-запрос, а комментарий или голос передаем как объект JSON:

Чтобы получить дополнительную информацию о файле, можно запросить подробности о связанных с ним объектах. В данном случае объекты могут характеризовать, например, поведение файла (объект behaviours) или URL, IP-адреса, доменные имена (объекты contacted_urls, contacted_ips, contacted_domains).

Интереснее всего объект behaviours. К примеру, для исполняемых файлов он будет включать в себя информацию о загружаемых модулях, создаваемых и запускаемых процессах, операциях с файловой системой и реестром, сетевых операциях.

Чтобы получить эту информацию, отправляем GET-запрос:

В ответе будет объект JSON с информацией о поведении файла:

Функции для работы с URL

В список возможных операций с URL входят:

  • отправка URL на сервер для анализа;
  • получение информации об URL;
  • анализ URL;
  • получение комментариев пользователей VirusTotal по нужному URL;
  • отправка своих комментариев по определенному URL;
  • получение результатов голосования по определенному URL;
  • отправка своего голоса за какой-либо URL;
  • получение расширенной информации о URL;
  • получение информации о домене или IP-адресе нужного URL.

Большая часть указанных операций (за исключением последней) выполняется аналогично таким же операциям с файлами. При этом в качестве идентификатора URL могут служить либо строка с URL, закодированная в Base64 без добавочных знаков «равно», либо хеш SHA-256 от URL. Реализовать это можно следующим образом:

Чтобы отправить URL для анализа, необходмо использовать POST-запрос:

В ответ мы увидим дескриптор URL (по аналогии с дескриптором файла):

Идентификатор id из этого дескриптора используем для получения информации об анализе файла через GET-запрос типа /analyses (об этом запросе ближе к концу статьи).

Получить информацию о доменах или IP-адресах, связанных с каким-либо URL, можно, применив GET-запрос типа /network_location (здесь используем Base64 или SHA-256 идентификатор URL):

Остальные операции с URL выполняются так же, как и аналогичные операции работы с файлами.

Функции работы с доменами и IP-адресами

Этот список функций включает в себя:

  • получение информации о домене или IP-адресе;
  • получение комментариев пользователей VirusTotal по нужному домену или IP-адресу;
  • отправку своих комментариев по определенному домену или IP-адресу;
  • получение результатов голосования по определенному домену или IP-адресу;
  • отправку голоса за домен или IP-адрес;
  • получение расширенной информации о домене или IP-адресе.

Все эти операции реализуются аналогично таким же операциям с файлами либо с URL. Отличие заключаются в том, что здесь используются непосредственно имена доменов или значения IP-адресов, а не их идентификаторы.

GET-запрос типа /analyses

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

Например, сформировать подобный запрос для файла можно вот так:

И вариант для URL:

Заключение

Мы прошлись по всем основным функциям API сервиса VirusTotal. Вы можете позаимствовать приведенный код для ваших проектов. Если используете вторую версию, понадобится следить за тем, чтобы не отправлять запросы слишком часто, но в третьей версии такого ограничения пока что нет. Рекомендую выбрать именно ее, поскольку и возможности здесь тоже намного шире. К тому же рано или поздно она станет основной.

Ссылки

Еще по теме: Как ловят создателей вирусов

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *