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: Rename an Analysis with a Python Script

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

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

For other scripting options, see:

Note: The Python script in this task is structured to be as similar as possible to those in the other download script tasks listed above.

Permissions Required

The script requires that special user Anonymous has the following permissions for the analysis A of interest.

See Modifying the Script for information on modifying the script to specify credentials for a non-Anonymous user with the required permissions.

Other Requirements

The example script imports standard Python modules argparse, os, and subprocess.

You will need a Python installation to run the script. If you do not have a local installation, you can use the cspython shipped with CodeSonar:

  1. Make sure that $CSONAR/codesonar/bin is in your PATH, where $CSONAR is the CodeSonar installation directory.
  2. To run the script, invoke Python with cspython (rather than python as in the examples below).

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

The Renaming Script

The following script will change the name of

import argparse
import subprocess
import os

# Rename the analysis.
def rename_analysis(hubaddr, analysis_id, newname):
    curl_cmd = ['curl']

    def check_page(inarg):
        args = ['-o', os.devnull, '-w', '%{http_code}']
        if isinstance(inarg, str):
            args = args + [inarg]
        else:
            args = args + inarg
        http_code = subprocess.check_output(curl_cmd + args)
        return (int(http_code.strip())==200)

    # Make sure the Analysis page is accessible.
    analysis_html_url = '{0}/analysis/{1}.html'.format(hubaddr,analysis_id)
    if not check_page(analysis_html_url):
        print('Could not access analysis page for analysis {0}'.format(analysis_id))
        print('This may indicate one or more of the following.')
        print('- The analysis ID was not specified correctly.') 
        print('- You do not have ANALYSIS_READ permission for the analysis')
        exit(1)

    # Attempt to rename the analysis; check the HTTP response code.
    rename_arguments = ['-d', 'new_name={0}'.format(newname),
                        analysis_html_url]
    # ; check HTTP response code.
    if not check_page(rename_arguments):
        print('Could not rename analysis {0}'.format(analysis_id))
        print('Make sure you have ANALYSIS_WRITE permission for this analysis.')
        exit(1)
       
    # Fetch and output the updated Analysis page on success.  This is
    # not necessary and can be commented out: it just ensures that
    # the script outputs the updated page as specified in the Task description.
    subprocess.check_call(curl_cmd + [analysis_html_url])


# Set up. 
def go():
    parser = argparse.ArgumentParser(
        description=('Rename an analysis on a CodeSonar hub, '
                     + 'as specified by the command-line arguments.'))
        
    parser.add_argument("hub",
                        help="The hub URL.")
    parser.add_argument("aid",
                        help="The analysis ID of the analysis to rename")
    parser.add_argument("newname",
                        help="The new analysis name; must be URL-encoded.")
    args = parser.parse_args()

    allargs = (args.hub, args.aid, args.newname)
    if not any([a is None for a in allargs]):
        rename_analysis(*allargs)

go()

This Python script uses an HTTP POST request to send the new analysis name to the hub, just as the web form on the Analysis page would do if you were changing the name in the web GUI. It outputs the updated Analysis page HTML.

Using the Script

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

  1. Copy rename_analysis.py to a suitable directory. The remainder of these instructions will refer to this directory as rundir.
  2. Run the script:
    cd rundir
    python rename_analysis.py protocol://host:port aid newname
    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 whose name you wish to change.
    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
    • in file path/to/projname.prj_files/aid.txt, where path/to/projname.prj_files/ is the analysis directory, 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 the Analysis Details section of the corresponding Analysis page.
    newname is new name you wish to set for the analysis. It must be URL-encoded.
    The script will output information about its progress.
  3. Open the analysis page protocol://host:port/analysis/aid.html in your web browser to confirm that its name has changed (or look at the top of the output). If it hasn't, the most likely explanation is that Anonymous does not have ANALYSIS_WRITE permission for the analysis.

Invocation Example

Using the hub at http://[::1]:7341, change the name of the analysis with ID 3 to "My Renamed Analysis":

python rename_analysis.py http://[::1]:7341 3 My%20Renamed%20Analysis

Troubleshooting

Get more verbose output For more verbose curl output, edit rename_analysis.py so that curl is invoked with the -v flag. For example: 
curl_cmd=['curl', '-v']
No files downloaded If there is no HTML output, this indicates that cURL did not download anything. There are two possible reasons.
  • curl could not download the HTML file because it doesn't exist.
    Check to make sure that you can open the HTML file URL in a web browser. You may need to pass different hub location or analysis ID arguments to the script.
  • You have an HTTPS-enabled hub with a self-signed hub server certificate. To instruct curl to accept self-signed certificates, edit rename_analysis.py so that curl is invoked with the -k flag. For example: 
    curl_cmd=['curl', '-k']
Downloaded files contain "Permission Denied" messages If there is an output HTML file but it contains a "Permission Denied" message rather than an updated Analysis page, this indicates that Anonymous does not have ANALYSIS_READ and ANALYSIS_WRITE permission for the analysis. You will need to specify credentials for a user with these permissions.

Modifying the Script

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

Stop printing the updated HTML file to output

If you don't want to see the updated HTML file 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 rename_analysis.py to comment out the last line of code in function rename_analysis().

Read analysis ID from analysis directory

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

  1. In function go(), replace line 
    parser.add_argument("aid", help="The analysis ID of the analysis to rename.")
    with a line adding an adir argument. 
    parser.add_argument("adir", help="The analysis .prj_files directory.")
  2. In function go(), change the definition of allargs to: 
    allargs = (args.hub, args.adir, args.newname)
  3. Modify the rename_analysis() function header, and add two new lines to the very beginning of the function definition. 
    def rename_analysis(hubaddr, analysis_dir, newname):
    with open(os.path.join(analysis_dir,'aid.txt'),'r') as aidfile:
        analysis_id=aidfile.read()
  4. When you invoke the script, specify the analysis directory as the second argument.

    For example: using the hub at http://[::1]:7341, rename the analysis whose analysis directory is /myprojects/projectX.prj_files/ to "Another Renamed Analysis".

    python rename_analysis.py http://[::1]:7341 /myprojects/projectX.prj_files/ Another%20Renamed%20Analysis

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 script 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 rename_analysis.py to add the following setting before the curl_cmd setting. 
    with open('path/to/bearerfile','r') as bearerfile:
   bearer_token = bearerfile.read().strip()
    where
    path/to/bearerfile is the path to the file containing the bearer token you want to use.
  3. Edit rename_analysis.py to modify the setting of curl_cmd: 
    curl_cmd=['curl', '-H', f"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 script to specify a suitable user certificate.
  1. If the account does not already have a user certificate and key, generate them now.
  2. Edit rename_analysis.py to add the following settings before the curl_cmd setting.. 
    cert_path='path/to/usercert.pem'
key_path='path/to/certkey.pem'
    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 rename_analysis.py to modify the setting of curl_cmd: 
    curl_cmd=['curl', '-k', 
          '-X', 'POST',
          '-d', '"sif_sign_in=yes&sif_use_tls=yes&sif_log_out_competitor=yes"',
          '--cert', cert_path,
          '--key', key_path]
    Omit the -k argument if your hub's hub server certificate is not self-signed.
Hard-Coded Username/Password If you will be running the Python script under secure conditions, you may be willing to specify the account username and password directly in the Python script 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 Python script would be http://jean:xyz123@[::1]:7340.

Example: Use the hub user account with username jean and password xyz123 to authorize renaming the analysis with ID 3 on the hub at http://[::1]:7340 to "IMPORTANT! Keep This!":

python rename_analysis.py http://jean:xyz123@[::1]:7340 3 IMPORTANT%21%20Keep%20This%21
Username, password, and new name must all 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 Scripts

You can follow the overall structure of this script to create Python scripts that download other kinds of file from the hub.

In general, the process for constructing a script 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 script 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 Python script 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 Python script 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. The Python script in this task is structured to be as similar as possible to those in the .sh and .bat download script examples. You may prefer to do one or more of the following to take advantage of Python libraries.
    • Download pages as XML, and parse with xml.etree.ElementTree to extract required information. Note, however, that there are some cases where information that can be extracted from in the HTML version of a given GUI page type is not present in the XML version. For example, the Project ID of the analyzed project can be extracted from an HTML Analysis page but not from the XML (or CSV, or JSON) version of the same page.
    • Use subprocess.Popen() instead of subprocess.call() to let multiple fetches occur in parallel. This can provide significant improvements in running time if the script is fetching a large number of pages.
    • Use one of the following instead of invoking curl with subprocess methods.
      • urllib2 (Python 2) / urllib (Python 3)
      • requests (not in the Standard Library)
      • PycURL (not in the Standard Library)
    • Have the script URL-encode script arguments, rather than requiring that the user encode them. For example, you can use urllib.urlencode() (Python 2) / urllib.parse.urlencode() (Python 3).

Running Scripts Automatically

You can use your system tools to arrange for the Python script to be run automatically.

For example, if you are using cron, add the following line to your crontab to run rename_analysis.py at 2:05am every day, renaming the analysis on hub http://red:7341 whose analysis directory is /home/projectX.prj_files/ to "My New Name".

5 2 * * * python /path/to/rename_analysis.py http://red:7341 `cat /home/projectX.prj_files/aid.txt` My%20New%20Name

(Note: many use cases for automatic renaming could be addressed more straightforwardly by using the -name option to set the analysis name when the analysis is performed.)

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