Account Security
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.
Audit Logs record calls to the Soracom API made from your account. It is separate from the Napter Audit Logs feature, which records the connections made to your devices through the Napter on-demand remote access service.
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
- If the authenticated user is the root account,
- 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/authAPI are recorded. - Logs are retained for 24 hours.
- Logs can be copied.
- Logins to the User Console and calls made to the
- 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/authlog with status code401will be recorded as part of the MFA authentication process. This is normal behavior, and is not an indication of unauthorized access.
- Note that when MFA security is enabled for the root account or a SAM user, a
- 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/authare 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.
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:
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/apiTo 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:
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.