Add support for audit report (closes #111)

Author: tjarrettveracode

docs/analytics.md

@@ -6,8 +6,8 @@ The following methods call Veracode REST APIs and return JSON.
 
 1. The Reporting API is available to Veracode customers by request. More information about the API is available in the [Veracode Docs](https://docs.veracode.com/r/Reporting_REST_API).
 
-- `Analytics().create_report(report_type ('findings'),last_updated_start_date(opt), last_updated_end_date (opt), scan_type (opt), finding_status(opt), passed_policy(opt), policy_sandbox(opt), application_id(opt), rawjson(opt), deletion_start_date(opt), deletion_end_date(opt))`: set up a request for a report. By default this command returns the GUID of the report request; specify `rawjson=True` to get the full response. Dates should be specified as `YYYY-MM-DD HH:MM:SS` with the timestamp optional. Options include:
-  - `report_type`: required, currently supports `findings`, `scans`, and `deletedscans`.
+- `Analytics().create_report(report_type ('findings'),last_updated_start_date(opt), last_updated_end_date (opt), scan_type (opt), finding_status(opt), passed_policy(opt), policy_sandbox(opt), application_id(opt), rawjson(opt), deletion_start_date(opt), deletion_end_date(opt), start_date(opt), end_date(opt), audit_action(opt), target_user_id(opt), modifier_user_id(opt))`: set up a request for a report. By default this command returns the GUID of the report request; specify `rawjson=True` to get the full response. Dates should be specified as `YYYY-MM-DD HH:MM:SS` with the timestamp optional. Options include:
+  - `report_type`: required, currently supports `findings`, `scans`, `deletedscans`, and `audit`.
   - `last_updated_start_date`: required for `findings` report type, beginning of date range for new or changed findings or scans
   - `last_updated_end_date`: optional, end of date range for new or changed findings or scans
   - `scan_type`: optional, one or more of 'Static Analysis', 'Dynamic Analysis', 'Manual', 'Software Composition Analysis', 'SCA'. `SCA` is only supported for the `findings` report type.
@@ -19,6 +19,43 @@ The following methods call Veracode REST APIs and return JSON.
   - `deletion_start_date`: required for `deletedscans` report type, beginning of date range for deleted scans.
   - `deletion_end_date`: optional, end of date range for deleted scans.
   - `sandbox_ids`: optional, array of sandbox IDs (integers) for which to return results
+  - `start_date`: required for `audit` report type, beginning of date range for audit events
+  - `end_date`: optional for `audit` report type, end of date range for audit events
+  - `audit_action`: optional for `audit` report type. An array of audit actions to include in the report. Examples include `Login`, `Login Account`, `Auth`, `Create`, `Delete`, `Update`
+  - `target_user_id`: optional for `audit` report type. The numeric user id of the user for which you want to retrieve audit events that happened to the user.
+  - `modifier_user_id`: optional for `audit` report type. The numeric user id of the user for which you want to retrieve audit events that were caused by the user.
+
+- `Analytics().create_findings_report(last_updated_start_date(opt), last_updated_end_date (opt), scan_type (opt), finding_status(opt), passed_policy(opt), policy_sandbox(opt), application_id(opt), rawjson(opt))`: set up a request for a findings report. By default this command returns the GUID of the report request; specify `rawjson=True` to get the full response. Dates should be specified as `YYYY-MM-DD HH:MM:SS` with the timestamp optional. Options include:
+  - `start_date`: required, beginning of date range for findings
+  - `end_date`: optional, end of date range for findings
+   - `scan_type`: optional, one or more of 'Static Analysis', 'Dynamic Analysis', 'Manual', 'Software Composition Analysis', 'SCA'.
+  - `finding_status`: optional, 'Open' or 'Closed'. Applies only to the `findings` report.
+  - `passed_policy`: optional, boolean. Applies only to the `findings` report.
+  - `policy_sandbox`: optional, 'Policy' or 'Sandbox'
+  - `application_id`: optional. The numeric application id of an application whose findings you want to include in the report.
+  - `rawjson`: optional, defaults to False. Returns full response if True, the GUID of the request if false
+
+- `Analytics().create_scans_report(start_date, end_date(opt), scan_type(opt), policy_sandbox(opt), application_id(opt), rawjson(opt))`: set up a request for a scans report. By default this command returns the GUID of the report request; specify `rawjson=True` to get the full response. Dates should be specified as `YYYY-MM-DD HH:MM:SS` with the timestamp optional. Options include:
+  - `start_date`: required, beginning of date range for scans
+  - `end_date`: optional, end of date range for scans
+  - `scan_type`: optional, one or more of 'Static Analysis', 'Dynamic Analysis', 'Manual'.
+  - `policy_sandbox`: optional, 'Policy' or 'Sandbox'
+  - `application_id`: optional. The numeric application id of an application whose scans you want to include in the report.
+  - `rawjson`: optional, defaults to False. Returns full response if True, the GUID of the request if false
+
+- `Analytics().create_deleted_scans_report(start_date, end_date(opt), application_id(opt),rawjson(opt))`: set up a request for a deleted scans report. By default this command returns the GUID of the report request; specify `rawjson=True` to get the full response. Dates should be specified as `YYYY-MM-DD HH:MM:SS` with the timestamp optional. Options include:
+  - `start_date`: required, beginning of date range for deleted scans
+  - `end_date`: optional, end of date range for deleted scans
+  - `application_id`: optional. The numeric application id of an application whose deleted scans you want to include in the report.
+  - `rawjson`: optional, defaults to False. Returns full response if True, the GUID of the request if false
+
+- `Analytics().create_audit_report(start_date, end_date(opt), audit_action(opt), target_user_id(opt),                         modifier_user_id(opt),rawjson(opt))`: set up a request for an audit log report. By default this command returns the GUID of the report request; specify `rawjson=True` to get the full response. Dates should be specified as `YYYY-MM-DD HH:MM:SS` with the timestamp optional. Options include:
+  - `start_date`: required, beginning of date range for audit events
+  - `end_date`: optional, end of date range for audit events
+  - `audit_action`: optional. An array of audit actions to include in the report. Examples include `Success`, `Logged out`, `Create`, `Delete`, `Update`
+  - `target_user_id`: optional. The numeric user id of the user for which you want to retrieve audit events that happened to the user.
+  - `modifier_user_id`: optional. The numeric user id of the user for which you want to retrieve audit events that were caused by the user.
+  - `rawjson`: optional, defaults to False. Returns full response if True, the GUID of the request if false
 
 - `Analytics().get(guid, report_type(findings))`: check the status of the report request and return the report contents when ready. Note that this method returns a tuple of `status` (string) and `results` (list); when `status` is `COMPLETED`, the `results` list will populate with results. Also, you need to specify the type of data expected by the GUID with `report_type`; this defaults to `findings`.
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = 'veracode_api_py'
-version = '0.9.61'
+version = '0.9.62'
 authors = [ {name = "Tim Jarrett", email="[email protected]"} ]
 description = 'Python helper library for working with the Veracode APIs. Handles retries, pagination, and other features of the modern Veracode REST APIs.'
 readme = 'README.md'
@@ -22,4 +22,4 @@ dependencies = {file = ["requirements.txt"]}
 [project.urls]
 "Homepage" = "https://github.com/veracode/veracode-api-py"
 "Bug Tracker" = "https://github.com/veracode/veracode-api-py/issues"
-"Download" = "https://github.com/veracode/veracode-api-py/archive/v_0961.tar.gz"
+"Download" = "https://github.com/veracode/veracode-api-py/archive/v_0962.tar.gz"

samples/reportingapi_audit_sample.py

@@ -0,0 +1,32 @@
+import time
+import sys
+import json
+import datetime
+from veracode_api_py import Analytics
+
+wait_seconds = 15
+
+print('Generating audit report...')
+theguid = Analytics().create_report(report_type="audit", start_date='2025-05-01',end_date='2025-05-05')
+
+print('Checking status for report {}...'.format(theguid))
+thestatus,theaudits=Analytics().get_audits(theguid)
+
+while thestatus != 'COMPLETED':
+    print('Waiting {} seconds before we try again...'.format(wait_seconds))
+    time.sleep(wait_seconds)
+    print('Checking status for report {}...'.format(theguid))
+    thestatus,theaudits=Analytics().get_audits(theguid)
+
+recordcount = len(theaudits)
+
+print('Retrieved {} audit records'.format(recordcount))
+
+if recordcount > 0:
+    now = datetime.datetime.now().astimezone()
+    filename = 'report-{}'.format(now)
+    with open('{}.json'.format(filename), 'w') as outfile:
+        json.dump(theaudits,outfile)
+        outfile.close()
+
+    print('Wrote {} audit records to {}.json'.format(recordcount,filename))

samples/reportingapi_deleted_sample.py

@@ -7,7 +7,7 @@
 wait_seconds = 15
 
 print('Generating deleted scans report...')
-theguid = Analytics().create_report(report_type="deletedscans",deletion_start_date='2024-07-01',deletion_end_date='2024-12-31')
+theguid = Analytics().create_deleted_scans_report(start_date='2024-07-01',end_date='2024-12-31')
 
 print('Checking status for report {}...'.format(theguid))
 thestatus,thescans=Analytics().get_deleted_scans(theguid)
@@ -20,7 +20,7 @@
 
 recordcount = len(thescans)
 
-print('Retrieved {} scans'.format(recordcount))
+print('Retrieved {} deleted scans'.format(recordcount))
 
 if recordcount > 0:
     now = datetime.datetime.now().astimezone()
@@ -29,4 +29,4 @@
         json.dump(thescans,outfile)
         outfile.close()
 
-    print('Wrote {} findings to {}.json'.format(recordcount,filename))
+    print('Wrote {} deleted scan records to {}.json'.format(recordcount,filename))

samples/reportingapi_sample.py

@@ -7,7 +7,7 @@
 wait_seconds = 15
 
 print('Generating report...')
-theguid = Analytics().create_report(report_type="findings",last_updated_start_date="2023-07-01 00:00:00")
+theguid = Analytics().create_findings_report(start_date="2023-07-01 00:00:00")
 
 print('Checking status for report {}...'.format(theguid))
 thestatus,thefindings=Analytics().get(theguid)

setup.py

@@ -7,15 +7,15 @@
 setup(
   name = 'veracode_api_py',         
   packages = ['veracode_api_py'],   
-  version = '0.9.61',      
+  version = '0.9.62',      
   license='MIT',        
   description = 'Python helper library for working with the Veracode APIs. Handles retries, pagination, and other features of the modern Veracode REST APIs.',   
   long_description = long_description,
   long_description_content_type="text/markdown",
   author = 'Tim Jarrett',                  
   author_email = '[email protected]',      
   url = 'https://github.com/tjarrettveracode',  
-  download_url = 'https://github.com/veracode/veracode-api-py/archive/v_0961.tar.gz',    
+  download_url = 'https://github.com/veracode/veracode-api-py/archive/v_0962.tar.gz',    
   keywords = ['veracode', 'veracode-api'],   
   install_requires=[            
           'veracode-api-signing'

veracode_api_py/analytics.py

@@ -6,7 +6,7 @@
 from .apihelper import APIHelper
 
 class Analytics():
-   report_types = [ "findings", "scans", "deletedscans" ]
+   report_types = [ "findings", "scans", "deletedscans", "audit" ]
 
    findings_scan_types = ["Static Analysis", "Dynamic Analysis", "Manual", "SCA", "Software Composition Analysis" ]
    scan_scan_types = ["Static Analysis", "Dynamic Analysis", "Manual" ]
@@ -17,30 +17,42 @@ class Analytics():
    def create_report(self,report_type,last_updated_start_date=None,last_updated_end_date=None,
                      scan_type:list = [], finding_status=None,passed_policy=None,
                      policy_sandbox=None,application_id=None,rawjson=False, deletion_start_date=None,
-                     deletion_end_date=None, sandbox_ids:list = []):
+                     deletion_end_date=None, sandbox_ids:list = [], start_date=None, end_date=None,
+                     audit_action:list = [], target_user_id:int = None, modifier_user_id:int = None):
 
       if report_type not in self.report_types:
          raise ValueError("{} is not in the list of valid report types ({})".format(report_type,self.report_types))
 
       report_def = { 'report_type': report_type }
 
-      if last_updated_start_date:
-         report_def['last_updated_start_date'] = last_updated_start_date
-      else:
-         if report_type in ['findings','scans']:
+      if report_type in ['audit']:
+         if start_date:
+            report_def['start_date'] = start_date
+         else:
+            raise ValueError("{} report type requires a start date.").format(report_type)
+         
+         if end_date:
+            report_def['end_date'] = end_date
+
+      if report_type in ['findings','scans']:
+         if last_updated_start_date:
+            report_def['last_updated_start_date'] = last_updated_start_date
+         else:
             raise ValueError("{} report type requires a last updated start date.").format(report_type)
 
-      if last_updated_end_date:
-         report_def['last_updated_end_date'] = last_updated_end_date
-         
-      if deletion_end_date:
-         report_def['deletion_end_date'] = deletion_end_date
+         if last_updated_end_date:
+            report_def['last_updated_end_date'] = last_updated_end_date
 
-      if deletion_start_date:
-         report_def['deletion_start_date'] = deletion_start_date
-      else:
-         if report_type == 'deletedscans':
-            raise ValueError("{} report type requires a deleteion start date.").format(report_type)
+      if report_type == 'deletedscans':   
+         if deletion_start_date:
+            report_def['deletion_start_date'] = deletion_start_date
+         else:
+            raise ValueError("{} report type requires a deletion start date.").format(report_type)
+
+         if deletion_end_date:
+            report_def['deletion_end_date'] = deletion_end_date
+
+#  clean this part up, make it object oriented, probably switch report creation by report type and create sub methods
 
       if len(scan_type) > 0:
          if report_type == 'findings':
@@ -65,6 +77,15 @@ def create_report(self,report_type,last_updated_start_date=None,last_updated_end
 
       if sandbox_ids:
          report_def['sandbox_ids'] = sandbox_ids
+
+      if len(audit_action) > 0:
+         report_def['audit_action'] = audit_action
+
+      if target_user_id:
+         report_def['target_user_id'] = target_user_id
+
+      if modifier_user_id:
+         report_def['modifier_user_id'] = modifier_user_id
 
       payload = json.dumps(report_def)
       response = APIHelper()._rest_request(url=self.base_url,method="POST",body=payload)
@@ -74,6 +95,31 @@ def create_report(self,report_type,last_updated_start_date=None,last_updated_end
       else:
          return response['_embedded']['id'] #we will usually just need the guid so we can come back and fetch the report
 
+   def create_findings_report(self, start_date, end_date=None,
+                     scan_type:list = [], finding_status=None, passed_policy=None,
+                     policy_sandbox=None, application_id=None,rawjson=False):
+      return self.create_report(report_type='findings', last_updated_start_date=start_date,
+                                last_updated_end_date=end_date,scan_type=scan_type,
+                                finding_status=finding_status, passed_policy=passed_policy,
+                                policy_sandbox=policy_sandbox, application_id=application_id,rawjson=rawjson) 
+
+   def create_scans_report(self, start_date, end_date=None, scan_type:list = [], 
+                           policy_sandbox=None, application_id=None, rawjson=False):
+      return self.create_report(report_type='scans', last_updated_start_date=start_date, 
+                                last_updated_end_date=end_date, scan_type=scan_type,
+                                policy_sandbox=policy_sandbox, application_id=application_id,rawjson=rawjson)
+
+   def create_deleted_scans_report(self, start_date, end_date=None, application_id=None,
+                                   rawjson=False):
+      return self.create_report(report_type='deleted_scans', deletion_start_date=start_date, 
+                                deletion_end_date=end_date, application_id=application_id,
+                                rawjson=rawjson)
+   
+   def create_audit_report(self, start_date, end_date=None, audit_action:list=[], target_user_id:int=None, 
+                           modifier_user_id:int=None):
+      return self.create_report(report_type='audit', start_date=start_date, end_date=end_date, audit_action=audit_action,
+                                target_user_id=target_user_id, modifier_user_id=modifier_user_id)
+      
    def get_findings(self, guid: UUID):
       thestatus, thefindings = self.get(guid=guid,report_type='findings')
       return thestatus, thefindings
@@ -84,7 +130,11 @@ def get_scans(self, guid: UUID):
 
    def get_deleted_scans(self, guid: UUID):
       thestatus, thescans = self.get(guid=guid,report_type='deletedscans')
-      return thestatus, thescans   
+      return thestatus, thescans
+
+   def get_audits(self, guid: UUID):
+      thestatus, theaudits = self.get(guid=guid, report_type='audit_logs')  
+      return thestatus, theaudits 
 
    def get(self,guid: UUID,report_type='findings'):
       # handle multiple scan types