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: Find the Most Recent Analysis of a Named Project with a Windows Batch (.bat) File

You can use a script to find the most recent analysis of a named project.

This task provides a batch file that finds the most recent analysis of a project (specified by name), 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 project P of interest and its most recent analysis A.

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 Download Batch File

The following file will download the CSV project search results for the project (or projects) on the hub specified in the first argument to the file whose name matches the second argument. It will use these results to generate a summary CSV document that lists, for each project found:

Both CSV files are stored in the directory specified in the third argument to the file.

@ECHO off
set CALL_DIR=%CD%
set HUB=%1
set PROJECT_NAME=%2
set SAVEDIR=%3

set PROJECT_SEARCH_CSV="%HUB%/project_search.csv?query=project%%3D"%PROJECT_NAME%"&scope=all"
set CURL_CMD=curl
set RESULT_FNAME=overall_results.csv
set SEARCH_FNAME=project_search_results.csv

cd /D %SAVEDIR%
rm -fr * 

echo project id, most recent analysis id, notes >%RESULT_FNAME%

(%CURL_CMD% %PROJECT_SEARCH_CSV% -o %SEARCH_FNAME%)

set /a LINECOUNT=0
FOR /f %%j in ('find "" /v /c ^<%SEARCH_FNAME%') DO set /A LINECOUNT=%%j

:: If no results, report and exit.
if %LINECOUNT% == 1 (
   echo No projects with URL-encoded name %PROJECT_NAME% were found.
   echo This may indicate one or more of the following.
   echo - The project name was not specified correctly (remember to URL-encode^).
   echo - You do not have PROJECT_EXISTS permission for the specified project.
   cd /D %CALL_DIR%
   exit /b
)
:: If multiple results, report and keep going.
if %LINECOUNT% GTR 2 (
   echo Found multiple projects with URL-encoded name '%PROJECT_NAME%'.
   echo The script will attempt to report the most recent analysis of each.
)

for /F "skip=1 tokens=*" %%L in (%SEARCH_FNAME%) do (
   call :handle_csv_line "%RESULT_FNAME%" "%%L"
)
cd /D %CALL_DIR%
exit /b

:handle_csv_line
set OUTFILE=%1
set LINE=%2
:: obtain last column of line
set LASTCOLUMN=
set /A COUNTER=0
:LOOPBEGIN
set /A COUNTER+=1
for /F "tokens=%COUNTER% delims=," %%A in (%LINE%) do (
    if "%%A"=="" goto :LOOPEND
    set LASTCOLUMN=%%A
    goto :LOOPBEGIN)
:LOOPEND
:: extract URL type and ID from last column
set LASTFIELD=
set SECONDLASTFIELD=
set /A COUNTER=0
:LOOPBEGIN
set /A COUNTER+=1
for /F "tokens=%COUNTER%* delims=/" %%A in (%LINE%) do (
    if "%%B"=="" goto :LOOPEND
    set SECONDLASTFIELD=%%A
    set LASTFIELD=%%B
    goto :LOOPBEGIN)
:LOOPEND

set RESULT_TYPE=%SECONDLASTFIELD%
set RESULT_ID=%LASTFIELD:~0,-4%

if "%RESULT_TYPE%"=="analysis" (
    echo -,%RESULT_ID%,- >> %OUTFILE%
)  else (
    if "%RESULT_TYPE%"=="project" (
        SETLOCAL ENABLEDELAYEDEXPANSION
        set "NO_ANALYSIS=No most recent analysis found. Either: a) project %RESULT_ID% has"
        set "NO_ANALYSIS=!NO_ANALYSIS! no analyses or b) you do not have ANALYSIS_EXISTS"
        set "NO_ANALYSIS=!NO_ANALYSIS! permission for the most recent analysis."
        echo %RESULT_ID%,-,!NO_ANALYSIS! >> %OUTFILE%
        ENDLOCAL
    ) else (
        echo Unexpected result type %RESULT_TYPE% in search results.
        )
    )
)

exit /b

This batch file works as follows.

  1. It constructs a query string using the project search language to specify that
  2. It accesses the specified hub to download the CSV version of the Project Search Results page for the constructed query string, saving it in the specified output directory with basename project_search_results.csv.

    This is the same file you would download if you did the following.

    1. Navigate to the Home page in the web GUI.
    2. Select projects on the hub from the search domain/scope menu.
    3. Enter project="<pname>" in the search text box, where <pname> is the name of the project you want to find. (Do not URL-escape <pname>.)
    4. Click the Search button.
      (A Project Search Results page will open to show the search results.)
    5. Click the CSV link in the Project Search Results page to obtain the CSV version of the page.
    You may like to try this now so you can see the following.
  3. For each line in the CSV file (representing a project whose name is <pname>) except for the first (which is a header line), it does the following.
    1. Inspects the last entry in the line (representing the URL corresponding to the result), extracting the following information.
      1. Whether it is for an Analysis page or a Project page.
        If the former, this is the Analysis page corresponding to the last analysis of the project. If the latter, no last analysis could be found and the hub has fallen back to linking to the project's Project page.
        For more information about CodeSonar URL schemes, see GUI Reference: Page Type Properties.
      2. The "ID" component of the URL: this is an Analysis ID if the URL is for an Analysis page; a Project ID if the URL is for a Project page.
    2. Uses this extracted information to compose and write a line in the result CSV file, which is stored in the specified output directory with basename overall_results.csv.

Using the Batch File

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

  1. Create a directory to save your result files in. The remainder of these instructions will refer to this directory as savedir.
  2. Copy find_project_analysis.bat to a suitable directory. The remainder of these instructions will refer to this directory as rundir.
    This should not be anywhere under savedir, since the file starts by deleting everything in that directory.
  3. Run the file:
    cd rundir
    find_project_analysis protocol://host:port projname savepath
    where
    protocol is the protocol for your hub: http or https.
    host:port is the location of your hub.
    projname is the name of the project whose last analysis you want to find. It must be URL-encoded.
    savepath is the path to the savedir directory you created in the first step.
    The file will output information about each file it downloads.
  4. Inspect the contents of savedir. It should contain two files.
  5. Open project_search_results.csv to see your results.

Invocation Examples

Using the hub at http://[::1]:7341, find the most recent analysis of the project named "My Favorite Project", saving the results in directory c:\tmp\csvout:

find_project_analysis http://[::1]:7341 My%20Favorite%20Project c:\tmp\csvout

Troubleshooting

Get more verbose output For more verbose curl output, edit find_project_analysis.bat so that curl is invoked with the -v flag. For example: 
set CURL_CMD=curl -v
No project_search_results.csv file If your output directory does not contain file project_search_results.csv, there are two possible reasons.
  • curl could not download the CSV file. The possible causes are as follows.
    • It is trying to download a page that does not exist.
      Check to make sure that you can open the CSV file URL in a web browser. You may need to pass a different hub location argument to the file.
  • You have an HTTPS-enabled hub with a self-signed hub server certificate. To instruct curl to accept self-signed certificates, edit find_project_analysis.bat so that curl is invoked with the -k flag. For example: 
    set CURL_CMD=curl -k
project_search_results.csv lists no results If your output directory contains file project_search_results.csv but it does not list any results, there are two possibilities.
  • There are no projects on the hub whose (URL-encoded) name matches the one specified.
    Check that you have specified the name correctly, and that it is URL-encoded. If necessary, try executing your search
  • There are one or more such projects, but Anonymous does not have PROJECT_EXISTS permission for any of them. You will need to specify credentials for a user with the required permissions.

Similarly, if project_search_results.csv lists fewer results than expected, it is likely to be because Anonymous does not have PROJECT_EXISTS permission for all matching projects.
overall_results.csv lists project IDs rather than analysis IDs This indicates that Anonymous has PROJECT_EXISTS permission for the project(s) of interest, but does not have ANALYSIS_EXISTS permission for the most recent analysis of each. You will need to specify credentials for a user with the required permissions.

Modifying the Batch File

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

Match project name substrings, rather than matching exactly

To change a search to perform substring matching rather than exact matching, we need to edit the corresponding field-condition to change its operator from = to :.
Because of URL-encoding, this becomes a change from %3D to %3A in the query string constructed by the file.

  1. Edit the file to change the line setting PROJECT_SEARCH_CSV to 
    set PROJECT_SEARCH_CSV="%HUB%/project_search.csv?query=project%%3A"%PROJECT_NAME%"&scope=all"
  2. Try running the edited file to see how substring matching affects the results.

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 find_project_analysis.bat to add the following setting after the SAVEDIR 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 find_project_analysis.bat to modify the setting of CURL_CMD: 
    CURL_CMD=curl -H "Authorization: Bearer %BEARER_TOKEN%"

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 find_project_analysis.bat to add the following settings after the SAVEDIR 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 find_project_analysis.bat to modify the setting of CURL_CMD:
    If your hub's hub server certificate is self-signed: 
    CURL_CMD=curl -k %POST_ARGS% %CERT_AUTH%
    Otherwise: 
    CURL_CMD=curl %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 batch 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 batch file would be http://jean:xyz123@[::1]:7340.

Example: Use the hub user account with username jean and password xyz123 to authorize finding the most recent analysis of the project named "Project X " on the hub at http://[::1]:7340, saving the results in directoryc:\tmp\csvout:

find_project_analysis http://jean:xyz123@[::1]:7340 PROJECT%20X c:\tmp\csvout
Both username and password must also 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.

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/.