Audit Logs

When using Soracom in a multi-user organization, you may want to periodically check for indications of unauthorized access. Audit Logs provides detailed information about calls to the Soracom API performed against your Soracom account, including access to the User Console and Soracom CLI usage.

When combined with Soracom Access Management (SAM), Audit Logs can be used to check the behavior of SAM users.

Log Details

Audit Logs will record the following information:

The timestamp of API access
The IP address (IPv4/IPv6) used to call the API
The username corresponding to the authenticated user
- If the authenticated user is the root account, <root user> will be recorded
- If the authenticated user is a SAM user, the username will be recorded
The path of the API request
The status code of the API request

Subscriptions

The following Audit Logs options are available:

Standard Option - This option is included by default for all Soracom accounts. The following features are provided in this option:
- Logins to the User Console and calls made to the /v1/auth API are recorded.
- Logs are retained for 24 hours.
- Logs can be copied.
Enterprise Option - This optional subscription extends the functionality of the Standard Option with the following features:
- Calls to all APIs are recorded.
- Logs are retained for 366 days.
- Logs can be filtered by API for easier searching.
- Logs can be downloaded.

Limitations

For security, individual logs cannot be deleted.
Similarly, for security, the recording of logs cannot be selectively disabled for certain users.
The following events are not recorded:
- Access to Soracom Lagoon
- Authentication failure events other than Multi-Factor Authentication failures
  - Note that when MFA security is enabled for the root account or a SAM user, a /v1/auth log with status code 401 will be recorded as part of the MFA authentication process. This is normal behavior, and is not an indication of unauthorized access.
- API Sandbox activity
Information about the access method (User Console, API, or CLI) is not recorded.
If your root account password or any SAM user credentials are shared in your organization, Audit Logs cannot determine which individual is accessing your account. You may have to rely on the IP address information for further details.
As logs for APIs other than /v1/auth are not recorded in the Standard Option, when subscribing to the Enterprise Option, you will not be able to view such logs prior to when the subscription is enabled. Similarly, when unsubscribing from and subsequently re-subscribing to the Enterprise Option, you will not be able to view logs from the previous Enterprise Option subscription.
Logs are recorded asynchronously, and do not reflect access in real-time.

Viewing Logs

Login to the User Console. From the Menu, open the Audit Logs screen. The latest Audit Logs will be visible.

https://console.soracom.io

If you are subscribed to the Enterprise Option, you can use the API menu to filter the logs.

Downloading Logs

If you are subscribed to the Enterprise Option, you can also download a copy of the logs for easier auditing.

Login to the User Console. For security, in order to download Audit Logs, you must login using your root account email address and password.
From the Menu, open the Audit Logs screen.
Click the Download button.
Select the time range of logs that you want to download. Then click Get link.

Depending on the amount of logs recorded within the specified time range, the log may take a few minutes to prepare.

Once the log has been prepared, an email containing a download link will be sent to the account's primary email address.

Changing Subscription

Subscribing to the Audit Logs Enterprise Option will incur a monthly service fee until subscription is cancelled. Refer to the Pricing & Fee Schedule for more information.

Login to the User Console. For security, in order to change your Audit Logs subscription, you must login using your root account email address and password.
From the Menu, open the Audit Logs screen.
A notification indicating your current Audit Logs option will be displayed above the list of logs.
- To subscribe to the Enterprise Option, click the Subscribe link.
- To unsubscribe from the Enterprise Option, click the Unsubscribe link.
After reviewing the details of the subscription change, click the Subscribe or Unsubscribe button to confirm the change.

When changing subscriptions, the new option may take up to 20 minutes to take effect.

Programmatic Usage

You can also access Audit Logs using the Soracom API or CLI in order to integrate a periodic audit procedure as part of your operations.

Soracom API

To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Reference Guide for instructions on how to use the API Key and Token in API requests.

Then, use the getApiAuditLogs API to retrieve logs:

Global
Japan

curl -X GET \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Accept: application/json' \
>  https://g.api.soracom.io/v1/audit_logs/api

curl -X GET \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Accept: application/json' \
>  https://jp.api.soracom.io/v1/audit_logs/api

To limit the API to a specific time range, use the from_epoch_ms and to_epoch_ms query parameters in the request URL. You can also use the limit query parameter to limit the number of logs returned by the API.

If Audit Logs contains more log entries than the specified limit, the API response will also return a value link in the response header indicating the request URL to use to retrieve the next set of logs.

If you are subscribed to the Enterprise Option, you can also use the api_kind query parameter to filter the logs based on the API path. Ensure that the API path is URL encoded within the request URL.

Soracom CLI

To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.

Then, run the following command to retrieve logs:

Global
Japan

soracom audit-logs api get --coverage-type g

soracom audit-logs api get --coverage-type jp

Similar to the API, you can use the --from-epoch-ms and --to-epoch-ms flags to limit the response to a specific time range. You can also use the --limit flag to limit the number of logs returned by the CLI.

Compared to the API usage, you can use the --fetch-all flag to automatically perform pagination and return a all logs at once.

If you are subscribed to the Enterprise Option, you can also use the --api-kind flag to filter the logs based on the API path.

Account Security