codesonar generate_hubbearerfile.py: Create/Delete a Hub User

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.

If you access the manual through the hub's Web GUI, the functionality will not be suppressed because the hub is a web server.
Alternatively, your browser may allow you to explicitly disable the security setting that suppresses functionality. See the CodeSonar FAQ for more information.

CodeSonar^® 9.0p0 Hot Tips

CONFIDENTIAL

CodeSecure Inc

codesonar generate_hubbearerfile.py: Create/Delete a Hub User Session and Bearer File

The codesonar generate_hubbearerfile.py subcommand can be used for two different purposes:

Create a user session and save its associated bearer token to a hub bearer file.
Once generated, this file can be supplied with the -hubbearerfile option to any codesonar subcommands that require hub authentication.
Delete the user session associated with a hub bearer file.

The expected use case for this command is in deploying CodeSonar in a containerized context. You can run codesonar generate_hubbearerfile.py in a temporary container to obtain a bearer token and store it to a persistent location.

Overview
Command Line
Using codesonar generate_hubbearerfile.py

Overview

The codesonar generate_hubbearerfile.py command can be used for two different purposes:

Create a new user session and save its associated bearer token in a specified file with owner-only permissions. The file can subsequently be used for bearer authentication.
Delete the user session associated with a hub bearer file.

generate_hubbearerfile.py is a codesonar Python subcommand.

Command Line

There are two forms of the command line.

Create a user session and save its bearer token.	codesonar generate_hubbearerfile.py [protocol://]host:port path/to/out_bearerfile \ [-hubuser username] [-hubcacert path/to/certfile] \ [--make-dirs, --makedirs, --parent, -p] [--overwrite, -f] [--expires-in num] \ [--overflow-ok] [--keepalive, --keep-alive] \ [--note msg, --message msg, -m msg] [--pool poolname]
Delete a user session.	codesonar generate_hubbearerfile.py [protocol://]host:port path/to/in_bearerfile \ --delete [--unlink, -u] [-hubcacert path/to/certfile]

Create a user session and save its bearer token

Use a command line of the following form to create a hub user session and save its associated bearer token to a file.

codesonar generate_hubbearerfile.py [protocol://]host:port path/to/out_bearerfile \
[-hubuser username] [-hubcacert path/to/certfile] \
[--make-dirs, --makedirs, --parent, -p] [--overwrite, -f] [--expires-in num] \
[--overflow-ok] [--keepalive, --keep-alive] \
[--note msg, --message msg, -m msg] [--pool poolname]

[protocol://]host:port	The hub where the user session is to be created.
path/to/out_bearerfile	Write the session's bearer token to the file at this location. If the file already exists, fail unless --overwrite is specified. If one or more of the directories in the specified path do not exist, fail unless --make-dirs or --overwrite is specified. The file owner will be set to the system user who runs this command. The file permissions will set to allow access only to the file owner.
[-hubuser username]	The username of the hub user account that will be the session user. If -hubuser uname is specified, CodeSonar will request a password for uname Otherwise, CodeSonar will request both a hub username and a password.
[-hubcacert path/to/certfile]	[HTTPS hubs only] If you are using an HTTPS hub with an untrusted hub server certificate, do the following. Download the hub server certificate from the hub Configure HTTPS page. Save a copy of the certificate to your local machine in Base-64 ASCII text format (often called "PEM" format). We will refer to this file as path/to/certfile. Specify -hubcacert path/to/certfile in your codesonar generate_hubbearerfile.py command. If your HTTPS hub has a trusted hub server certificate, or you are not using an HTTPS hub, you do not need to specify this option.
[--make-dirs] [--mkdirs] [--parents] [-p]	The command will create any directories in the specified path that do not already exist. If not specified, behavior depends on whether or not --overwrite is specified: --overwrite specified: the command will behave as if --make-dirs is also specified. --overwrite not specified: the command will fail if any of the directories do not exist.
[--overwrite] [-f]	Any existing file at path/to/out_bearerfile will be overwritten. If not specified, the command will fail if file path/to/out_bearerwfile already exists. When --overwrite is specified, the command will behave as if --make-dirs is also specified.
[--expires-in num]	The Expires property for the session will initially be set to num seconds after the current time. If not specified, the default initial Expires value will be used. If --keepalive is specified, the session Expires value may be extended when the session is used.
[--overflow-ok]	If there are no available licensed session slots for the requested session, create an overflow session. If not specified, the command will fail if there is no available licensed session slot. For more information, see Session Limits.
[--keepalive] [--keep-alive]	Set the session Keep Alive? property to "true". If not specified, session Keep Alive? will be set to "false".
[--note msg] [--message msg] [-m msg]	Set the session Note property to msg. The specified msg must be appropriately quoted/escaped.
[--pool poolname]	Set the session Pool property to poolname.

Delete a user session

Use a command line of the following form to delete the hub user session associated with a specified bearer file.

codesonar generate_hubbearerfile.py [protocol://]host:port path/to/in_bearerfile \
--delete [--unlink, -u] [-hubcacert path/to/certfile]

[protocol://]host:port	The hub associated with the user session.
path/to/in_bearerfile	Delete the session whose bearer token is stored in this file.
--delete -d	Delete the indicated user session.
[--unlink] [-u]	Delete the bearer file (path/to/in_bearerfile) after deleting the session. When --unlink is specified, the command will behave as if --delete is also specified.
[-hubcacert path/to/certfile]	[HTTPS hubs only] If you are using an HTTPS hub with an untrusted hub server certificate, do the following. Download the hub server certificate from the hub Configure HTTPS page. Save a copy of the certificate to your local machine in Base-64 ASCII text format (often called "PEM" format). We will refer to this file as path/to/certfile. Specify -hubcacert path/to/certfile in your codesonar generate_hubbearerfile.py command. If your HTTPS hub has a trusted hub server certificate, or you are not using an HTTPS hub, you do not need to specify this option.

Using codesonar generate_hubbearerfile.py

The expected use case for this command is in deploying CodeSonar in a containerized context.

Suppose that:

You are running your container commands as container_user,
and
you wish to authenticate your CodeSonar commands using the hub user account with username alex.

Then the general technique is as follows.

Determine a persistent location for storing the bearer file.
For example, if you are using Docker then you can save the bearer file to a Docker volume.
The remaining steps will refer to this location as /persistent/pathto/bearerfname.
Sign in to the container system as container_user.
Use a temporary container to set up your credentials by running a codesonar generate_hubpwfile.py command. For example, to create a session for user alex on the hub at http://myhub.example.com:7340:

codesonar generate_hubbearerfile.py http://myhub.example.com:7340 \
/persistent/path_to/bearerfname \
-hubuser alex --overwrite
When you start this temporary container, enter the password for alex when prompted. If the session is created successfully, its bearer token will be saved as the only contents of file /persistent/path_to/bearerfname.
- If the file already exists, it will be overwritten.
- If any directories in the specified file path do not already exist, they will be created.
- The file owner will be container_user.
- The file permissions will be set to owner-only (that is, container_user-only).
In the container (or containers) where you are deploying CodeSonar, provide your generated bearer file whenever you need to authenticate a codesonar subcommand:
-auth bearer -hubbearerfile /persistent/pathto/bearerfname
For example:
codesonar analyze MyProject http://myhub.example.com:7340 \
-auth bearer -hubbearerfile /persistent/pathto/bearerfname \
[... remainder of command]
If you want to explicitly delete the session after using it, you can do this with another codesonar generate_hubpwfile.py command.
codesonar generate_hubbearerfile.py http://myhub.example.com:7340 \
/persistent/path_to/bearerfname --delete --unlink
For more information on the various ways in which a session can end, see Ending a Session.

Note: you will probably find it most convenient to store the /persistent/pathto/bearerfname string in a variable and then refer to this variable in your various commands.