Skip to main content

Running Scheduled Scans

The following are the new additions to the Checkmarx API: public CxWSResponseRunID ScanWithSchedulingWithCron(string sessionId, CliScanArgs args, string cronString, long utcEpochStartTime, long utcEpochEndTime) This method is intended for generating a new scan job according to the CliScanArgs input, cron expression and start and end dates. Cron-Expressions Cron-Expressions are strings that are actually made up of seven sub-expressions, that describe individual details of the schedule. These sub-expression are separated with white-space, and represent:

1. Seconds

2. Minutes

3. Hours

4. Day-of-Month

5. Month

6. Day-of-Week

7. Year (optional field)

An example of a complete cron-expression is the string "0 0 12 ? * WED" - which means "every Wednesday at 12:00 pm".

Individual sub-expressions can contain ranges and/or lists. For example, the day of week field in the previous (which reads "WED") example could be replaces with "MON-FRI", "MON, WED, FRI", or even "MON-WED,SAT".

Wild-cards (the '*' character) can be used to say "every" possible value of this field. Therefore the '*' character in the "Month" field of the previous example simply means "every month". A '*' in the Day-Of-Week field would obviously mean "every day of the week".

All of the fields have a set of valid values that can be specified. These values should be fairly obvious - such as the numbers 0 to 59 for seconds and minutes, and the values 0 to 23 for hours. Day-of-Month can be any value 0-31, but you need to be careful about how many days are in a given month! Months can be specified as values between 0 and 11, or by using the strings JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV and DEC. Days-of- Week can be specified as values between 1 and 7 (1 = Sunday) or by using the strings SUN, MON, TUE, WED, THU, FRI and SAT.

The '/' character can be used to specify increments to values. For example, if you put '0/15' in the Minutes field, it means 'every 15 minutes, starting at minute zero'. If you used '3/20' in the Minutes field, it would mean 'every 20 minutes during the hour, starting at minute three' - or in other words it is the same as specifying '3,23,43' in the Minutes field.

The '?' character is allowed for the day-of-month and day-of-week fields. It is used to specify "no specific value". This is useful when you need to specify something in one of the two fields, but not the other.

The 'L' character is allowed for the day-of-month and day-of-week fields. This character is short-hand for "last", but it has different meaning in each of the two fields. For example, the value "L" in the day-of-month field means "the last day of the month" - day 31 for January, day 28 for February on non-leap years. If used in the day-of-week field by itself, it simply means "7" or "SAT". But if used in the day-of-week field after another value, it means "the last xxx day of the month" - for example "6L" or "FRIL" both mean "the last friday of the month". When using the 'L' option, it is important not to specify lists, or ranges of values, as you'll get confusing results.

The 'W' is used to specify the weekday (Monday-Friday) nearest the given day. As an example, if you were to specify "15W" as the value for the day-of-month field, the meaning is: "the nearest weekday to the 15th of the month".

The '#' is used to specify "the nth" XXX weekday of the month. For example, the value of "6#3" or "FRI#3" in the dayof-week field means "the third Friday of the month".

Start and end times (utcEpochStartTime & utcEpochEndTime)

Those long type parameters are used to determine a repetitive (scheduled) scan start and end time. The default values are 0 (zero) in order to indicate that it should start now (though initiate a scan by the cron expression schedule) and never end / last forever.

Other (non default) values indicate the start and end time. They contain the second count from the Epoch (January 1st 1970) on UTC time. Note that the start time HAS to be in the future and that there must be at least one scan scheduled in between start and end time.

SOAP to REST Mapping

This section covers SOAP to REST migration and mapping of our legacy SOAP based SDK to the new REST APIs. It is recommended to use this reference only once CxSAST V8.8.0 is installed.

ScanWithSchedulingWithCron

PUT /sast/project/{projectId}/scheduling

Define specific project’s scan scheduling settings. Parameters include - scheduleType and scheduleDays.

GET /sast/scans/{id}

Get details of a specific scan. Returns status and stage of the scan.

GET /sast/scanSettings/{projectId}

Get a specific project’s scan settings. Returns preset and engine configuration of the scan.

GET /sast/scansQueue

Get details of all scans in the scans queue. Returns wide-ranging scan information (e.g., stageDetails, engineId, languages, teamId, loc, origin, queuePosition, isIncremental, isPublic, origin, creation date, etc..).

GET sast/scans?scanStatus={status}

Get all scans with a specific scan status (Scanning, Finished, Canceled or Failed).

GET /sast/scans?last={numberOfLastScans}

Get all scans according to number of last scans.

GET /sast/scans

Get all scans.