Get audit history

get https://api.stackhawk.com/api/v1/org/{orgId}/audit

List Audits

Lists audit events for this organization.

Returns a paginated list of Audit Records.

Audit events cover user actions such as inviting someone to an Organization INVITE_USER, or creating an application APPLICATION_ADDED and completing a scan SCAN_COMPLETED.

Audit events can also cover organization centric activity that's not tied to a user, such as scan data being shared with a third party EXTERNAL_ALERTS_SENT.

Audit logs are only available for Enterprise tier plans, and only accessible by Owner and Admin roles.

Audit Records

Represents an auditable event from within the StackHawk platform.

Parameter	Default	Description
id	""	UUID identifier of this audit.
userActivityType	"UNKNOWN"	User audit activity from use of StackHawk platform.
organizationActivityType	"UNKNOWN"	Organization audit activity for a StackHawk organization.
organizationId	""	The organizationId associated with this audit.
userId	""	The userId associated with this audit.
userName	""	The userName associated with this audit.
userEmail	""	The user email associated with this audit.
payload	""	A JSON payload with specifics of the audit event.
timestamp	0	SecondsSinceEpoch timestamp of the event.
userIPAddr	""	The ip address associated with this audit.

Organization audit activity will have empty userId, userName and userEmail fields.
The timestamp is represented in milliseconds from unix epoch.
User audit activity will have the identifying userActivityType field. Organization audit activity has organizationActivityType.
The userIPAddr field is always empty.
The payload is a stringified JSON object with a variety of applicable fields for the audit event. Different audit types may have different payload fields.

{
  "id": "6a1292de-2fae-4107-a5ec-2374d3b2ec3f",
  "organizationId": "a0e05070-e594-4e0d-b72d-6c0033dc8cce",
  "userId": "4302d7d2-2d58-4b38-8051-34f0d73b7d87",
  "userName": "Ron Swanson",
  "userEmail": "[email protected]",
  "payload": "{\"scanId\":\"c4e3884b-2e21-4b04-b892-9d7934b3980e\",\"appName\":\"Pawnee Park Service Admissions\",\"envName\":\"Preprod\",\"apiSource\":\"HAWKSCAN\"}",
  "userIPAddr": "",
  "timestamp": 1587289200000,
  "userActivityType": "SCAN_COMPLETED"
}

const auditrecord = {
	id: "",
	userActivityType: "UNKNOWN",
	organizationActivityType: "UNKNOWN",
	organizationId: "",
	userId: "",
	userName: "",
	userEmail: "",
	payload: "",
	timestamp: 0,
	userIPAddr: "",
}

interface AuditRecord {
	id: string
	userActivityType: AuditUserActivityType
	organizationActivityType: AuditOrganizationActivityType
	organizationId: string
	userId: string
	userName: string
	userEmail: string
	payload: string
	timestamp: number
	userIPAddr: string
} 

const auditrecord: AuditRecord = {
	id: "",
	userActivityType: "UNKNOWN",
	organizationActivityType: "UNKNOWN",
	organizationId: "",
	userId: "",
	userName: "",
	userEmail: "",
	payload: "",
	timestamp: 0,
	userIPAddr: "",
}

public class AuditRecord {

	public String id;
	public AuditUserActivityType userActivityType;
	public AuditOrganizationActivityType organizationActivityType;
	public String organizationId;
	public String userId;
	public String userName;
	public String userEmail;
	public String payload;
	public long timestamp;
	public String userIPAddr;

}

data class AuditRecord(
	var id: String,
	var userActivityType: AuditUserActivityType,
	var organizationActivityType: AuditOrganizationActivityType,
	var organizationId: String,
	var userId: String,
	var userName: String,
	var userEmail: String,
	var payload: String,
	var timestamp: Long,
	var userIPAddr: String
)

class AuditRecord:
	id = ""
	userActivityType = "UNKNOWN"
	organizationActivityType = "UNKNOWN"
	organizationId = ""
	userId = ""
	userName = ""
	userEmail = ""
	payload = ""
	timestamp = 0
	userIPAddr = ""

struct AuditRecord {
	id: &str,
	userActivityType: AuditUserActivityType,
	organizationActivityType: AuditOrganizationActivityType,
	organizationId: &str,
	userId: &str,
	userName: &str,
	userEmail: &str,
	payload: &str,
	timestamp: i64,
	userIPAddr: &str,
}

Audit Types

StackHawk collects and shares two kinds of audit information from the API:

User Audit Events types: these typically stem from use of the StackHawk Platform, API or Scanner, and are logged as userActivityType in audit records.
Organization Events orgTypes: these pertain to an organization, but may not specifically refer to a user, and are logged as organizationActivityType in audit records.

User Activity Types

Parameter	Description
UNKNOWN	Unknown activity.
INVITE_USER	An invite to join the organization was sent.
USER_INVITE_REVOKED	An invite to join the organization was rescinded.
REMOVE_USER	A user was removed from the organization.
SCAN_STARTED	A scan was started.
SCAN_ERRORED	A running scan errored.
SCAN_COMPLETED	A running scan completed.
INTEGRATION_ADDED	An integration was added to the organization.
INTEGRATION_MODIFIED	An integration was changed.
INTEGRATION_REMOVED	An integration was removed from the organization.
TECH_FLAG_ADDED	A tech flag has been applied to an application.
TECH_FLAG_MODIFIED	A tech flag was modified.
TECH_FLAG_REMOVED	A tech flag was removed.
SCAN_CONFIG_MODIFIED	A scan configuration was modified.
APPLICATION_ADDED	An application was added to the organization.
APPLICATION_MODIFIED	An application was changed.
APPLICATION_REMOVED	An application was removed from the organization.
ENVIRONMENT_ADDED	An environment was added.
ENVIRONMENT_MODIFIED	An environment was changed.
ENVIRONMENT_REMOVED	An environment was removed.
ALERT_RULE_TRIAGED	An alert was triaged.
API_KEY_ADDED	A API key was added.
API_KEY_REMOVED	A API key was removed.
USER_JOINED_ORG	A new user joined the integration.
ALERT_RULE_REMOVED	A scan alert rule was removed.
USER_PASSWORD_MODIFIED	A user's password was changed.
USER_PREFERENCES_MODIFIED	A user's preferences were modified.
ORG_MODIFIED	An organization was modified.
SCAN_REMOVED	A scan was deleted.
SUBSCRIPTION_MODIFIED	A billing subscription was changed.
SUBSCRIPTION_ADDED	A billing subscription was added.
ORG_DOWNGRADED	The organization lost users, app, integrations or features forcefully.
DOWNLOAD_SCAN_ASSET	A scan asset was downloaded.
CUSTOM_TEST_SCRIPT_ADDED	A custom test script has been registered for the organization.
CUSTOM_TEST_SCRIPT_REMOVED	A custom test script has been removed from an organization.
APPLICATION_POLICY_ADDED	A scan policy has been added to an application.
APPLICATION_POLICY_MODIFIED	An application policy was changed.
APPLICATION_POLICY_REMOVED	A policy was removed from an application.
TEAM_ADDED	A team was added.
TEAM_UPDATED	A team was updated.
TEAM_DELETED	A team was deleted.
USER_MODIFIED	User preferences were changed.
INTEGRATION_START_AUTHORIZATION	Authorize integration started.
APPLICATIONS_ADDED_FOR_REPOS	Applications were created & added to repos.
REPO_MODIFIED	A repo was updated.
REPO_REMOVED	A repo was deleted.
ORGANIZATION_POLICY_ADDED	A scan policy has been added to an organization.
ORGANIZATION_POLICY_MODIFIED	An organization policy was changed.
ORGANIZATION_POLICY_REMOVED	A policy was removed from an organization.

Organization Activity Types

Parameter	Description
UNKNOWN	Unknown activity.
EXTERNAL_ALERTS_SENT	Scan result data for this organization was sent to a third party.
EXTERNAL_API_UNSUCCESSFUL_RESPONSE	A third party API responded with a non-2xx response when invoked on behalf of this organization.
ORG_USER_INVITE_REMINDER_SENT	A user invite reminder was sent out to invitees of this organization.

Audit Payload

The Audit payload is a json string blob with contextual data added for this audit event.

These are field names that can show up in an audit payload.
There is not an explicit schema for the audit payload object for each audit type, but field names are consistent and may include the following:

userId
appId
envId
userName
appName
envName
pathsCount
triageStatus
integration
scanId
orgId
provider
inviteEmail
apiSource
productName
assetType
customScriptId
customScriptName
teamName
teamId
previousTeamName
previousTeamAppList
previousTeamUserList
previousMemberRole
memberRole
memberEmail
rawMessage
rawStatusCode

Audit type availability

StackHawk will add audit type annotations to be requested, sometimes before there are actual audit events of the type even sent by the platform.

Most audit event payload fields may change, and two audit events of the same type may have different payload fields. The overall structure of an audit event is stable.

We strive for accuracy with sent audit events, but please let us know of any deficiencies.