Task: Delete an Analysis with a Python Script

• Permissions Required
• Other Requirements
• The Deletion Script
• Using the Script
• Modifying the Script
• Writing Other Scripts
• Running Scripts Automatically
• Links

Permissions Required

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

• ANALYSIS_DELETE A
• ANALYSIS_READ A
• PROJECT_READ P

See Modifying the Script for information on modifying the script 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:

• add $CSONAR/third-party/curl/inst/bin/ to the front of your PATH,
  or
• edit the script so that the setting of curl_cmd specifies the full path to $CSONAR/third-party/curl/inst/bin/curl.

The Deletion Script

The following script will delete

• the analysis whose analysis ID matches the second argument passed to the script,
• on the hub specified in the first argument to the script.

import argparse
import subprocess
import os
import re

# Delete the specified analysis from the specified hub.
def del_analysis(hubaddr, analysis_id):
    curl_cmd = ['curl']

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

    analysis_html_url = f'{hubaddr}/analysis/{analysis_id}.html'

    # The relative URL to POST to is shown in the "action" attribute
    # of the "remove_analysis_form" form: extract it from there.
    analysis_dl = subprocess.Popen(curl_cmd + [analysis_html_url],
                                   stdout=subprocess.PIPE)
    analysis_page = analysis_dl.communicate()[0].decode()

    projpage_match = re.search(r'<form\s+name="remove_analysis_form"\s+method="POST"\s+action="([^"]*)">',
                               analysis_page)
    if projpage_match is None:
        print('Could not get analysis page', analysis_html_url)
        print('This is probably because of one of the following:')
        print('- you do not have ANALYSIS_READ permission for the analysis, or')
        print('- there is no such analysis.')
        exit(1)

    project_html_url = f'{hubaddr}{projpage_match.group(1)}'
    # Make sure the Project page is accessible, otherwise there is no
    # point trying to POST to it.
    if not check_page(project_html_url):
        print('Could not get project page', project_html_url)
        print('Make sure you have PROJECT_READ permission for this project.')
        exit(1)

    delete_args = ['-L',
                   '--cookie-jar','cookies.txt',
                   '-d', f'remove_analysis_id={analysis_id}',
                   project_html_url]
    subprocess.check_call(curl_cmd + delete_args)

    if check_page(analysis_html_url):
        print('Could not delete analysis', analysis_id)
        print('Make sure you have ANALYSIS_DELETE permission for the analysis.')
        exit(1)


# Set up.
def go():
    parser = argparse.ArgumentParser(
        description=('Delete an analysis from 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 for the analysis to delete.")
    args = parser.parse_args()

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

go()

This Python script 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:

• -L instructs cURL to follow redirects.
• --cookie-jar cookies.txt instructs cURL to use local file cookies.txt to manage any cookies involved in completing the command.
  File cookies.txt will be created in your working directory, if it does not already exist.

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 Script

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

1. Copy delete_analysis.py 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:

   • select a different rundir, or
   • edit the script to specify a different file name with --cookie-jar.
2. Run the script:
   cd rundir
   python delete_analysis.py 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 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 the analysis is no longer available.

Invocation Example

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

Troubleshooting

curl_cmd=['curl', '-v']

curl_cmd=['curl', '-k']

Modifying the Script

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

• Stop printing the resulting HTML file to output
• Read analysis ID from analysis directory
• Provide credentials for a non-Anonymous user

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.py to add the -o flag with a suitable value to the definition of delete_args:

   delete_args = ['-o', os.devnull,
                  '-L',              
                  '--cookie-jar', 'cookies.txt',
                  '-d', f'remove_analysis_id={analysis_id}',
                  project_html_url]

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 for the analysis to delete.")

   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)
   

3. Modify the del_analysis() function header, and add two new lines to the very beginning of the function definition.

   def del_analysis(hubaddr, analysis_dir):
       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, delete the analysis whose analysis directory is /myprojects/projectX.prj_files/.

   python delete_analysis.py http://[::1]:7341 /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 script to submit credentials for a suitable hub user account.

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

Running Scripts Automatically

You can use your system tools to arrange for the Python script 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.

5 2 * * * python /path/to/delete_analysis.py http://red:7341 `cat /home/projectX.prj_files/aid.txt`

Links

• Typical CodeSonar Tasks
• HTTP API Documentation
• The CodeSonar Hub
• CodeSonar GUI Reference