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
General

User Sessions and Anonymous Sessions

Some CodeSonar hub interactions take place in sessions, which can be either user sessions or anonymous sessions.

User sessions and anonymous sessions are both licensed resources.

CodeSonar sessions can be divided into user sessions and anonymous sessions.
In some cases, sessions of either type can be overflow sessions.

user session A session that has been authenticated by a non-Anonymous hub user account (including Administrator).
anonymous session A session that has not been authenticated by a non-Anonymous hub user account.
These sessions are treated as belonging to special user Anonymous, and are only available if Anonymous has G_SIGN_IN permission.
overflow session One of the following.

An overflow session has reduced functionality. There is no access to licensed behavior, even if the Session User would otherwise have the relevant permissions through their assigned roles. A message specifying that the user is in an "overflow session" will be displayed above the GUI page footer.

Note: overflow sessions cannot be created through the HTTP API. If no licensed slots are available, session creation through the HTTP API will fail.

If a licensed slot becomes available, you can claim it by ending the overflow session and then creating a new session.

Properties

This section describes each of the properties of a session. The full list of properties is (in alphabetical order):

Name Description
Bearer Token A unique security token associated with the session. You can present this token to perform bearer authentication.

The Bearer Token is reported as a result of explicitly creating a session on the User Sessions page or through the HTTP API. It is not available afterward, or for sessions created by other means.
Expires The date and time at which the session will expire. If Keep Alive? is set to "true", this will be repeatedly extended while activity is taking place in the session.
If not explicitly specified when the session is created, the initial Expires value is computed by adding the hub's HTTP session timeout to the current date/time.
ID A unique numeric identifier for the session.
Keep Alive? "True" if the Expires date/time should be extended when the session is not idle. If set to "false", the Expires value is fixed at the time the session is created and does not change.

Session extension works as follows. Each time you use a session with Keep Alive?="true", CodeSonar checks the current date/time.

  • If the remaining session time (that is, the interval between the current date/time and Expires) is substantially less than the hub's HTTP session timeout, the Expires setting is updated to Enew, computed as
    Enew = the current date/time + the hub's HTTP session timeout
  • Otherwise, the Expires setting is not modified.
Note A user-specified note, provided when the session was initially created.
Overflow? "True" if this is an overflow session, "false" otherwise.
Precious? "True" if the session is protected from forced deletion, "false" otherwise.
Pool A text label naming the "pool" to which the session belongs. Two sessions with the same Pool value are considered to belong to the same pool.
Pools provide another dimension for imposing session limits. Along with the hub-wide and per-user limits, there is a user-pool limit for each pool. For example, suppose you have a "ci" pool that is used only by CodeSonar operations in your organization's continuous integration system. Setting a user-pool limit on the "ci" pool helps ensure that the continuous integration does not take up all available session slots.

New sessions are assigned to pools as follows.

Session Type Pool
browsing the hub's web GUI (whether signed in or anonymous) web
created on the User Sessions page noninteractive
created via the HTTP API a user-specified string
Session User The hub user account associated with the session.
If this user is Anonymous then the session is an anonymous session, otherwise it is a user session.

Per-user and user-pool session limits provide restrictions on the number of simultaneous user sessions with the same Session User.

Creating Sessions

Sessions can be created as shown in the following table.

    Permissions Required
Implicit Creation: GUI Signing in to the web GUI implicitly starts a user session.
Accessing the web GUI without signing in implicitly starts an anonymous session.
Explicit Creation: GUI You can create sessions for a given user from the corresponding User Sessions page.
  • Sessions created from the User Sessions page for special user Anonymous are anonymous sessions.
  • Sessions created from any other User Sessions page are user sessions.
Explicit Creation:
codesonar generate_hubbearerfile.py 		You can use codesonar generate_hubbearerfile.py to create a new user session and save its bearer token to a file.

For more information, see codesonar generate_hubbearerfile.py: Create/Delete a Hub User Session and Bearer File.
Explicit Creation: HTTP API POST /session/create-anonymous/[*]
POST /session/create-basic-auth/[*]
POST /session/create-impersonate/[*]
POST /session/create-new-account/[*]
POST /session/create-reset-password/[*]
POST /session/create-tls-client-certificate/[*]  

Ending a Session

The various mechanisms for ending a session are shown in the following table.

  Method Permissions Required
Ordinary Expiration A session is automatically deleted when its Expires timestamp is reached.
If Keep Alive?="true", the Expires value will be repeatedly extended while activity is taking place in the session.		  -
Forced Deletion A session with Precious?="false" can be forcibly deleted to allow creation of a new session.

Suppose a user U attempts to start a new session Sn in pool P.

  1. CodeSonar checks whether the current set of sessions for U is already at the per-user limit, and whether they are already at the user-pool limit for P.

    at per-user limit? True if the total number of current sessions with Session User=U and Overflow?="false" is greater than or equal to the per-user limit,
    False otherwise.
    at user-pool limit for P? True if the total number of sessions with Session User=U and Pool=P and Overflow?="false" is greater than or equal to the user-pool limit for P,
    False otherwise.
  2. If a forced deletion candidate was identified in the previous step, it is deleted.
  3. CodeSonar proceeds with attempting to start session Sn.
Note:
  • If there are multiple forced deletion candidates, CodeSonar will generally select the one with the closest Expires value.
  • The Precious? setting of the newly-requested session Sn does not affect forced deletion.
  • Anonymous sessions do not undergo forced deletion.
  -
Implicit Deletion: GUI If Sessions expire on browser close? is enabled for the hub, user sessions or anonymous sessions that were browsing the web GUI are deleted when you close the corresponding browser, unless the browser prevents this. -
Explicit Deletion: GUI The CodeSonar web GUI provides session deletion functionality in several contexts.
  • You can delete one or more sessions for a given user from the corresponding User Sessions page.
  • When you change a user password on the Settings or Account Editor page, you can optionally delete all sessions associated with that user. If you change your own password by this method, all your user sessions will be deleted except the GUI session you are using to perform the change.

    If you are changing the password because of a security breach or similar, we recommend also deleting the user's existing sessions. In other cases, you might decide that you wish to keep existing sessions. For example, if there is no security concern and the user has a long-lived session that is used to perform bearer authentication for automated operations, you might decide to keep the user's sessions rather than creating a new session and updating the automation.

  • Signing out of the hub will also delete the corresponding GUI session. Both user sessions and anonymous sessions can sign out.
Explicit Deletion:
codesonar generate_hubbearerfile.py		 You can use codesonar generate_hubbearerfile.py with the --delete option to delete the user session associated with a specified bearer file.

For more information, see codesonar generate_hubbearerfile.py: Create/Delete a Hub User Session and Bearer File.
Explicit Deletion: HTTP API DELETE /session/[*]
  • G_SIGN_IN
  • Deletes the session that is authenticating it.

Accessing Session Information

Session information is available in the CodeSonar GUI as follows.

User Sessions Detailed information about all sessions associated with the corresponding user, along with functionality for deleting sessions and creating new sessions.
License Utilization Current user session and anonymous session counts for the hub.

Session Limits

Session limits are applied at several levels of detail.

licensed anonymous sessions The maximum number of anonymous sessions that can run simultaneously on the hub.
  • If this many anonymous sessions are running on the hub and a user attempts to start another anonymous session, they will get an overflow session.
  • This is a licensed resource.
licensed user sessions The maximum number of user sessions that can run simultaneously on the hub.
  • If this many user sessions are running on the hub and hub user U attempts to start another user session, behavior is as follows.
  • This is a licensed resource.
per-user limit The total number of licensed sessions (that is, sessions with Overflow?="false") that a single non-Anonymous hub user can run simultaneously.
  • All hub users (except Anonymous) have the same per-user limit.
  • If a user U has this many licensed user sessions and attempts to start another session, the hub will attempt to forcibly delete one of U's existing sessions to make space available.
    • If this is successful and frees up a license slot, the new session will start as a licensed session
    • Otherwise, if the session creation request was via the HTTP API, it will fail.
    • Otherwise, the user will get an overflow session.
  • You can modify this limit.
user-pool limits For each pool, the maximum number of icensed sessions (that is, sessions with Overflow?="false") that a single non-Anonymous hub user can run simultaneously in that pool.
  • For any given pool P, all hub users (except Anonymous) have the same user-pool limit for P.
  • Different pools can have different limits.
  • If a user U attempts to start a new session in a pool P for which they are already running the maximum number of sessions, the hub will attempt to forcibly delete one of U's existing sessions to make space available.
    • If this is successful and frees up a license slot, the new session will start as a licensed session
    • Otherwise, if the session creation request was via the HTTP API, it will fail.
    • Otherwise, the user will get an overflow session.
  • You can modify these limits.

Changing per-user and user-pool limits

You can change the per-user and user-pool limits for your hub by editing the hub's constants.py file.

CodeSonar SaaS Note: If you are using CodeSonar SaaS, you will not have access to the constants.py file. Contact CodeSecure support if you wish to change these limits.

On the machine that is running the hub, do the following.

  1. Open $CSONAR/codesonar/py/hub/constants.py for editing, where $CSONAR is the base directory of the CodeSonar installation that is running the hub.
  2. Modify the session limit settings as required.
    MAX_SESSIONS_PER_USER The hub's per-user limit: a single value.
    MAX_SESSIONS_PER_USER_POOL The hub's user-pool limits, as a dictionary of pool_name:pool_limit pairs.
    • You can add new pairs to specify limits for any custom pool names you wish to use.
    • Specify a pool_limit of None if you don't want to impose a limit on the corresponding pool.
    • The entry with pool_name None is used for all pools that do not have specific entries in the dictionary.
      You can modify the pool_limit for this entry, but do not delete it.
  3. Save and close constants.py.
  4. Restart the hub so that your changes can take effect.

Bearer Authentication

A session's bearer token can be used to perform bearer authentication.

The expected use case for bearer authentication is for automated operations that are noninteractive or unattended, such as continuous integration or nightly scripts.

The general technique is as follows.

  1. Explicitly create a session in the web GUI, with codesonar generate_hubbearerfile.py, or via the HTTP API.
  2. Present the session's bearer token to authenticate your CodeSonar operations.

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