JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

CodeSonar® 9.2p0 CONFIDENTIAL CodeSecure Inc

Task: Delete an Analysis with a Windows Batch (.bat) File

You can use a script to delete an existing analysis from the command line.

Removing an analysis removes some, but not all, of the information associated with the analysis:

You might want to remove an analysis if:

This task provides a batch file for deleting a specified analysis, along with some suggestions for modifying the script to suit your needs.

For other scripting options, see:

Permissions Required

The file requires that special user Anonymous has the following permissions for the analysis A of interest and the analyzed project P.

See Modifying the Batch File for information on modifying the file to specify credentials for a non-Anonymous user with the required permissions.

Other Requirements

Use the cURL shipped with CodeSonar: $CSONAR/third-party/curl/inst/bin/curl, where $CSONAR is the CodeSonar installation directory. Either:

The Deletion Batch File

The following file will delete

@ECHO off
set HUB=%1
set ANALYSIS_ID=%2

set ANALYSIS_HTML_URL=%HUB%/analysis/%ANALYSIS_ID%.html
set CURL_CMD=curl -L --cookie-jar cookies.txt

(call:set_projurl %HUB% %ANALYSIS_HTML_URL% PROJECT_HTML_URL)

(%CURL_CMD%  -d remove_analysis_id=%ANALYSIS_ID% %PROJECT_HTML_URL%)
exit /b


:: The relative URL to POST to is shown in the "action" attribute
:: of the "remove_analysis_form" element: extract it from there and convert
:: to an absolute URL.

:set_projurl
set ANALYSIS_URL=%2

:: Get the LINE containing the opening tag of the "remove_analysis_form" form.
FOR /F "delims=" %%i IN ('%CURL_CMD% %ANALYSIS_URL% ^| findstr -r  /c:"form name=\"remove_analysis_form\"" 2^>nul') DO set LINE=%%i

:: The relative URL is between the 5th and 6th double quotes in this LINE.
FOR /F delims^=^"^ tokens^=6  %%i IN ("%LINE%") DO (call set %~3=%1%%i)

exit /b

This batch file uses an HTTP POST request to perform the deletion: the POST request is for the Project page for the analyzed project, and must specify remove_analysis_id=aid, where aid is the analysis ID of the analysis to be deleted. It outputs the HTML landing page that reports successful deletion.

The hub functionality for deleting an analysis entails several HTTP redirects across a single session. When you are using an anonymous session, as here, it must be tracked using cookies. The script uses cURL options to ensure that the redirects and cookies are properly accounted for:

Inspect the HTML source for an Analysis page to see the remove_analysis_form form and how its components correspond to the HTTP POST request constructed by the script.

Using the Batch File

To use this file with your hub, do the following.

  1. Copy delete_analysis.bat to a suitable directory. The remainder of these instructions will refer to this directory as rundir.

    Make sure you have full file permissions in rundir, and that using file rundir/cookies.txt to manage cookies for this task will not cause conflicts with other uses of rundir. If there is a problem, either:

  2. Run the file:
    cd rundir
    delete_analysis protocol://host:port aid
    where
    protocol is the protocol for your hub: http or https.
    host:port is the location of your hub.
    aid is the analysis ID for the analysis that you wish to delete.
    You can find the analysis ID:
    • in the URL specified at the end build/analysis command output, which will be of the form http://hub_location/analysis/analysis_id.html, or
    • by running the following command, where path\to\projname.prj_files\ is the analysis directory
      codesonar analysis_id.py path\to\projname.prj_files\
      or
    • in file path\to\projname.prj_files\aid.txt, where path\to\projname.prj_files\ is the analysis directory, or
    • in the Analysis Details section of the corresponding Analysis page.
    The file will output information about its progress.
  3. Open the analysis page protocol://host:port/analysis/aid.html in your web browser to confirm that the analysis is no longer available.

Invocation Example

Using the hub at http://[::1]:7341, delete the analysis with ID 3:

delete_analysis http://[::1]:7341 3

Troubleshooting

Get more verbose output For more verbose curl output, edit delete_analysis.bat so that curl is invoked with the -v flag. For example: 
set CURL_CMD=curl -v -L --cookie-jar cookies.txt
No files downloaded If there is no HTML output, this indicates that cURL did not download anything. This can occur if you have an HTTPS-enabled hub with a self-signed hub server certificate. To instruct curl to accept self-signed certificates, edit delete_analysis.bat so that curl is invoked with the -k flag. For example: 
set CURL_CMD=curl -k -L --cookie-jar cookies.txt
Downloaded files contain "Permission Denied" messages If there is an output HTML file but it contains a "Permission Denied" message rather than a page reporting successful deletion, this indicates that Anonymous does not have the required permissions. You will need to specify credentials for a user with these permissions.

Modifying the Batch File

You may wish to make one or more of the following modifications.

Stop printing the resulting HTML file to output

If you don't want to see the final HTML file notifying you of successful deletion as part of your script's output, you can redirect it to the null location by modifying your curl command. Note that if you make further changes that you need to debug later, you may wish to lift this suppression at least temporarily.

  1. Edit delete_analysis.bat so that curl is invoked with the -o flag and a suitable value. 
    set CURL_CMD=curl -o nul -L --cookie-jar cookies.txt

Read analysis ID from analysis directory

Instead of specifying the analysis ID on the command line, you can change the file to read the analysis directory from the command line and then read the most recent analysis ID from the analysis directory.

  1. Edit delete_analysis.bat so that the line setting ANALYSIS_ID is replaced with three lines: 
    set ANALYSIS_DIR=%2
set CSONAR=codesonar.exe
for /F "tokens=*" %%g in ('%CSONAR% analysis_id.py %ANALYSIS_DIR%') do (set ANALYSIS_ID=%%g)
    If it is not in your PATH, adjust the setting of CSONAR to include the full path to your codesonar.exe executable.
  2. When you invoke the script, specify the analysis directory as the second argument.

    For example: using the hub at http://[::1]:7341, delete the analysis whose analysis directory is C:\myprojects\projectX.prj_files\.

    delete_analysis http://[::1]:7341 C:\myprojects\projectX.prj_files\

Provide credentials for a non-Anonymous user

If your hub is configured so that special user Anonymous does not have the required permissions, you will need to edit the file to submit credentials for a suitable hub user account.

We recommend using bearer authentication. Alternative mechanisms are described in the table below.

For bearer authentication, do the following.

  1. If you do not already have a suitable session and bearer token to use, generate them now.
    1. Navigate to the User Sessions page for your selected hub user account.
    2. Use the Create Session form to create a new session with a suitably long Expires setting.
      When you click Create Session, the page will be reloaded and the Bearer Token for your new session will be displayed at the top of the page.
      IMPORTANT: Make a note of the Bearer Token now. Once you refresh or navigate away from this page there will be no further opportunity to view the token.
    3. Save the bearer token to a file. The remainder of these instructions will refer to this file as path\to\bearerfile.
  2. Edit delete_analysis.bat to add the following setting after the ANALYSIS_HTML_URL setting. 
    set /p BEARER_TOKEN=<path\to\bearerfile
    where
    path\to\bearerfile is the path to the file containing the bearer token you want to use.
  3. Edit delete_analysis.bat to modify the setting of CURL_CMD: 
    CURL_CMD=curl -L -H "Authorization: Bearer %BEARER_TOKEN%"
    Note that --cookie-jar cookies.txt has been removed: the HTTP redirects are all within the bearer session.

For more information about bearer authentication in CodeSonar, see User Sessions and Anonymous Sessions: Bearer Authentication.

If you don't want to use bearer authentication, you can choose one of the options from the following table.

Certificate If the hub is configured for certificate-based authentication, you can edit the file to specify a suitable user certificate.
  1. If the account does not already have a user certificate and key, generate them now.
  2. Edit delete_analysis.bat to add the following settings after the ANALYSIS_HTML_URL setting. 
    set CERT_PATH=path\to\usercert.pem
set KEY_PATH=path\to\certkey.pem
set CERT_AUTH=--cert %CERT_PATH% --key %KEY_PATH%
set POST_ARGS=-X POST -d "sif_sign_in=yes&sif_use_tls=yes&sif_log_out_competitor=yes"
    where
    path\to\usercert.pem is the path to the hub user account's user certificate.
    path\to\certkey.pem is the path to the private key corresponding to the user certificate.
  3. Edit delete_analysis.bat to modify the setting of CURL_CMD:
    If your hub's hub server certificate is self-signed: 
    CURL_CMD=curl -k -L --cookie-jar cookies.txt %POST_ARGS% %CERT_AUTH%
    Otherwise: 
    CURL_CMD=curl -L --cookie-jar cookies.txt %POST_ARGS% %CERT_AUTH%
Hard-Coded Username/Password If you will be running the batch file under secure conditions, you may be willing to specify the account username and password directly in the file invocation.

For example, if your hub location is http://[::1]:7340 and the hub user account has username jean and password xyz123, the first argument to the file would be http://jean:xyz123@[::1]:7340.

Example: Use the hub user account with username jean and password xyz123 to authorize deleting the analysis with ID 3 on the hub at http://[::1]:7340:

delete_analysis http://jean:xyz123@[::1]:7340 3
Username and password must both be URL-encoded.
Username/Password: Other See the curl man page for alternative username/password authentication mechanisms.

See CodeSonar HTTP API: Authentication for more information on authentication strategies.

Writing Other Batch Files

You can follow the overall structure of this file to create batch files that download other kinds of file from the hub.

In general, the process for constructing a file will be along the following lines.

  1. Determine the GUI page type you are interested in.
  2. Look at the the GUI reference page for your required page type to determine the following information.
    • The page's URL or URL scheme: use this to construct the URL or URLs for your file to download.
    • The alternative page output formats that are available: if you want to process pages in one of these formats rather than HTML, check that your required format is available and construct the download URLs accordingly.
    • The RBAC permissions required to access the page and its contents. If special user Anonymous does not have these permissions, the batch file will need to provide authentication credentials for a hub user account that has the permissions.
  3. If your script will be carrying out a task that modifies the hub database (adding, deleting, or modifying elements), inspect the GUI page HTML to look at the <form ... > element that provides access to the functionality you are interested in. Your script will need to include an HTTP POST request (via curl or similar) that corresponds to the one issued when the form is submitted.
  4. Make sure your batch file includes the following elements.
    • One or more download URLs, or a mechanism for constructing them.
    • Some way of handling the downloaded URLs: one of the following.
      • The location to which the URLs should be downloaded, or a way to obtain the location.
      • An explicit redirect to the null location.
      • No specific handling, so that the downloaded files are all part of the script output.
    • A curl invocation that acts on the the URL or URLs.
  5. See the troubleshooting notes above if you encounter problems.
  6. This task uses a batch file in order to be accessible to as many Windows users as possible. If you have access to PowerShell, you will probably prefer it over batch files for scripted hub interactions.
    You may also be interested in using Python scripts to interact with the hub: if you have no local Python installation, you can use the cspython executable shipped with CodeSonar.

Running Batch Files Automatically

You can use your system tools to arrange for the batch file to be run automatically.

However, a more suitable approach in most automatic analysis deletion use cases is to use the analysis auto-deletion functionality provided by the hub. This section is provided for completeness only.

For example, you may choose to use the Windows Task Scheduler.

Links

Note. This page contains references to HTTP API documentation, which is served directly by the hub and cannot be accessed via a file:// URL. For active HTTP API documentation links, start a hub (if one is not already running), then open the manual from the hub.

 

To report problems with this documentation, please visit https://support.codesecure.com/.