Contribute to SRTool: Difference between revisions

From Yocto Project
Jump to navigationJump to search
No edit summary
 
(32 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:SRTool]]
[[Category:SRTool]]
This page summarizes the Security Response Tool (SRTool) development process. We hope this will help you start contributing to the project. The SRTool is based on the Toaster codebase, so many of the process and debugging techniques apply.
This page summarizes the Security Response Tool (SRTool) development process. We hope this will help you start contributing to the project. The SRTool is based on the Yocto Project Toaster codebase (Django,Python,Javascript), so many of the process and debugging techniques apply.  
__FORCETOC__


__FORCETOC__
== Published content: General CVE management issues and the SRTool ==
* The SRTool paper for the Embedded Linux Conference, Edinburg 2018:
** https://events.linuxfoundation.org/wp-content/uploads/2017/12/Keeping-Up-With-The-Joneses-CVEs-David-Reyna-Wind-River-Systems.pdf�
* Wind River Blog about CVEs and the SRTool
** http://blogs.windriver.com/wind_river_blog/2018/11/security-response-management-risk-cost-and-best-practices-in-an-imperfect-world.html�


<br/>
<br/>
Line 8: Line 13:


<strong>1) Host requirements</strong>
<strong>1) Host requirements</strong>
The SRTool should in principle work on any host that supports Yocto Project. It requires "Python3", "Django >= 1.11", and "Sqlite3". A SQL GUI tool like 'sqlitebrowser' is recommended.


The required host package installation instructions are the same as Toaster, and the instructions can be found here: [http://www.yoctoproject.org/docs/latest/toaster-manual/toaster-manual.html#toaster-manual-start Toaster documentation]
The required host package installation instructions are the same as Toaster, and the instructions can be found here: [http://www.yoctoproject.org/docs/latest/toaster-manual/toaster-manual.html#toaster-manual-start Toaster documentation]


The SRTool was developed and tested with:
It was specifically developed and tested with:
  * Ubuntu 16.04
{| class="wikitable" style="text-align: left;"
  * Django 1.11 LTS
! Item
Later versions of the host or Django should work, but they have not been tested yet.
! Host 1
! Host 2
! Host 3
|-
|Host
|Ubuntu 20.04
|
|
|-
|Python3
|3.8.10
|
|
|-
|Django
|4.00
|
|
|-
|Sqlite3
|3.31.1
|
|
|-
|}
 


<strong>2) Cloning the SRTool</strong>
<strong>2) Cloning the SRTool</strong>
   <code> $ git pull ssh://git@push.yoctoproject.org/srtool && cd srtool </code>
 
   <code> $ git clone git://git.yoctoproject.org/srtool && cd srtool </code>
 
Here is the command if your SSH key is registered:
 
  <code> $ git clone ssh://git@push.yoctoproject.org/srtool && cd srtool </code>


<strong>3) Starting the SRTool</strong>
<strong>3) Starting the SRTool</strong>


Option #1: Restrict to the local browser:
Option #1: Restrict to the local browser:
   <code> $ ./bin/srtool start webport=localhost:9000 </code>
   <code> $ ./bin/srt start webport=localhost:9000 </code>


Option #2: Enable remote browsers:
Option #2: Enable remote browsers:
   <code> $ ./bin/srtool start webport=0.0.0.0:9000 </code>
   <code> $ ./bin/srt start webport=0.0.0.0:9000 </code>


<strong>NOTE</strong>: The first time you run the SRTool, there will be a delay (30 to 60 minutes) as the default CVE repositories (NIST, Mitre, ...) are scanned, scored, and loaded into the database. After that, the updates will be incremental.
<strong>NOTE</strong>: The first time you run the SRTool, there will be a delay (30 to 60 minutes) as the default CVE repositories (NIST, Mitre, ...) are scanned, scored, and loaded into the database. After that, the updates will be incremental.
Line 31: Line 68:
<strong>4) Create a superuser</strong>
<strong>4) Create a superuser</strong>


You will need to create at least one super user account to promote users to higher permission levels, for example for a user called 'my_admin':
You will need to create at least one super user account to promote users to higher permission levels:
    
    
   <code> $ ./bin/srt manage createsuperuser my_admin </code>  
   <code> $ ./bin/srt manage createsuperuser</code>  


<strong>5) Open browser to <IPADDR>:9000</strong>
<strong>5) Open browser to <IPADDR>:9000</strong>
Line 52: Line 89:


You can now log out of the superuser account and into your own account.
You can now log out of the superuser account and into your own account.
<br/>
<br/>


== Sanity Test Bring-up ==
You can use these steps to start a minimal instance of the SRTool to help validate that the host and the code base are working on your system. This will for example set the environment variable "SRTDBG_MINIMAL_DB=1" which will only fetch a few representative records from each data source.
<code>
  $ # Clone the SRTool
  $ git clone git://git.yoctoproject.org/srtool && cd srtool
  $ # Bring down the development assistance tools
  $ cp bin/dev_tools/* .
  $ # Prepare the venv and SRTool environment variables
  $ . prepare_environment.sh
  $ # Start the SRTool, trigger the CVE downloads
  $ ./restart.sh
  ...
  SRTool webserver started at http://0.0.0.0:9000
  $ # Create the initial superuser account, who can then create all other accounts
  $ ./super.sh
  SRT_MAIN_APP=yp
  The system will manage.
  Username: srtool
  Email address:
  Password:
  Password (again):
  Superuser created successfully.
  $
</code>
Sanity command test:
<code>
  $ ./bin/common/srtool_sanity_test.py -i
  * Host statistics ...
  Uname      = #44~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Mon May 22 13:39:36 UTC 2 x86_64
  Django      = (4, 0, 0, 'final', 0)
  Python3    = Python 3.10.12
  Sqlite3    = 3.37.2 2022-01-06
  Server PID  = 95890
  * Database statistics ... (use '-v' for details)
  * Table checks ...
  * Summary ...
  CVEs        = 219524
  Users      = 6
  Data sources= 51
  $
</code>
<br/>
== First Time Bring-up ==
== First Time Bring-up ==


* When you first start, you will have the CVEs from 2015 to 2018
* When you first start, you will have the CVEs from 2015 to 2023
* You will not have any Vulnerabilities, Investigations, or Defects until you (a) create them, and/or (b) integrate your defect system or other sustaining data.
* You will not have any Vulnerabilities, Investigations, or Defects until you (a) create them, and/or (b) integrate your defect system or other sustaining data.
* All CVEs will by default get the status "Historical".
* All CVEs will by default get the status "Historical".
Line 72: Line 157:
** Observe that the products are added together with new respective Investigations
** Observe that the products are added together with new respective Investigations
** Follow the new link to the new Investigations
** Follow the new link to the new Investigations
* You can create a Defect by:
** Open an Investigation record
** Click on "Create Defect"
** With the sample defect integration script, a simulated defect will be created and attached to the investigation
<br/>
<br/>


Line 88: Line 177:
** Automated updates from upstream CVEs and internal defect system
** Automated updates from upstream CVEs and internal defect system
** Ability to generate reports
** Ability to generate reports
** Correlate CVEs with products and release
** Simple customization for organizations
** Correlate CVEs with specific customer builds
** Correlate CVEs with products and release (IN PROGRESS)
** Correlate CVEs with specific customer builds (IN PROGRESS)
 
<br/>
<br/>


Line 106: Line 197:
** Releases are updated with the CVE fixes
** Releases are updated with the CVE fixes
** Resolved CVEs are reported to customers, public website
** Resolved CVEs are reported to customers, public website
<br/>
<br/>
== Testing the Alternate Sample Organization 'ACME' ==


== Adapting SRTool to your Organization ==
* An example alternate organization (master application) called "acme" is included.
* This code shows all the ways the SRTool can be easily customized to the needs of your organization
* To enable it and try it out, do the following:


1) Out of the box setup (NIST/MITRE)
<code>
    $ # Include the quick development tools
    $ cp bin/dev_tools/* .
    $ # Reset 'acme' as the master app/organization
    $ ./stop.sh
    $ ./master_app.sh acme
    $ ./start.sh
</code>


  (a) When SRTool starts up, it will automatically load the preset data sources.
* When you browse the SRTool pages, will now observe several differences
** In the top bar the text "[ACME]" will appear in several places. This shows how files like "lib/acme/templates/base.html" can take precedence over the default template files in "lib/srtgui".
** In the top left corner the "ACME" logo will appear. This is from "SRTOOL_LOCAL_LOGO" being defined in "datasource.json".
** If you click on the ACME logo you will be taken to an ACME hello page. This shows that "lib/acme/urls.py" has extended the URL map, plus how you can implement basic HTML pages in ACME's "lib/acme/views.py" and "lib/acme/templates/acme_hello.html".
** In the ACME hello page, there are links to custom table pages for Products and Defects. This shows how to implement custom Toaster Tables via "lib/acme/urls.py" and "lib/acme/tables.py"
** In the Products page, when you click "Export" a new report type "ACME Products Table" is appended. This shows how to extend and customize existing or new reports.


  (b) NIST and MITRE are examples of preset data sources, by default to import 2015 to 2018.
* To restore the default "yp" master application, do the following:
<code>
    $ ./stop.sh
    $ ./master_app.sh yp
    $ ./start.sh
</code>


To extend the coverage for these sources you just need to edit the NIST and MITRE data source JSON files.
== Adapting SRTool to your Organization ==
 
2) Instantiate your Organization


  (a) Create a directory under "bin", parallel to the "yp" directory
* You can use the sample alternate organization "acme" as a guide to adapt SRTool to your organization
* In this example, we will instantiate a new organization called "<strong>yoyodyne</strong>"
* You should be able to place all of your local content into these two directories:
** <strong>"./bin/yoyodyne"</strong>: this is your master datasource directory
** <strong>"./lib/yoyodyne"</strong>: this is your master Django App directory
* If you find you need to make changes in the core SRTool code, we recommend (in preferential order):
** See if you can make it a generic feature so that it can become part of the mainline codebase
** See if you can make an easy hook for the mainline code, so that your custom content can still reside in your directories
** Talk to us on how to easily have managed custom patches to the mainline code (we do this in Toaster)


  (b) Create a "datasource.json" file for the organizations settings
<strong>1) Instantiate your Organization</strong>


  (c) Define this "srtsetting" in the ""datasource.json" file to make this the default organization (not 'yp')
You can create a starting customization of the SRTool for your organization with these simple steps.
* In this example, we will use the name "yoyo" as a shorthand for a mythical "Yoyodyne Corporation".


<code>
<code>
    {
  $ cd /path_to/srtool_dir
      "name" : "datasource_org",
  $ copy bin/dev_tools/* .
      "helptext" : "Bin directory for the ACME Organization",
  $ ./stop.sh
      "value" : "acme"
  $ ./master_app.sh create yoyo
    },
  $ ./start.sh
</code>
</code>


  (d) Instantiate the organization's product list, and user list (if any)
* This script will perform the following actions:
** Copy the sample 'bin/acme' directory to 'bin/yoyo'
** Copy the sample 'lib/acme' directory to 'lib/yoyo'
** Rename the respective Acme/ACME/acme labels and filenames to Yoyo/YOYO/yoyo
** Set 'yoyo' as the new main application
* You now have access to all the preset custom features described above for the ACME sample organization, now for Yoyodyne.


  (e) Adapt a copy of the the "bin/yp/srtool_yp.py" to manage the resources
<strong>2) Add your defect system integration</strong>


3) Add defect system import
You will need to implement a defect integration backend script to scan your defect system and instantiate the CVE defects in SRTool database, and then keep them up to date.


You will implement a defect integration backend script (e.g. "bin/acme/srtool_defect.py") to scan your defect system and instantiate the CVE defects in SRTool database.
* An example implementation template for Jira is provided here.  
<code>
  bin/common/srtool_jira_template.py
</code>
* You can use this to guide your integration to Jira or to other defect systems.
* To see how to extend this template to your organization and yet maintain compatibility with upstream, see this section: [https://wiki.yoctoproject.org/wiki/SRTool_Developer_Page#Extending_and_customizing_common.2Ftemplate_code_files Extending and customizing common/template code files]
* Please contact the SRTool developers for assistance in your defect system integration effort.


  (a) Add the "--init" command
The main features of this example code, in addition to the Jira system access, is:


* This is the command that will initialize the SRTool database with your SRT related defects. Specifically, this command can used to bootstrap the SRTool database for you company's data.
*  The "--init" command
** This command that will initialize the SRTool database with your SRT related defects. Specifically, this command can used to bootstrap the SRTool database for your company's data
** It will create an "Investigation" for each defect, and attach it to the respective product
** It will create a "Vulnerability" to wrap the respective "Investigation"
** If should find the respective CVE record if it exists, and attach that to the created "Vulnerability"
** If a "Vulnerability" record already exists for the defect's CVE, then this script should attach the new "Investigation" to that "Vulnerability" record.
* The "--update" command
** This will scan your CVE-related defects
** If the matching defect record in the SRTool database does not exist, then treat it like the "--init" command.
** It will update the SRTool defect record with the current defect system state
** If the defect has changed priority (or any other important state information), it will create a "Notification" event to the respective manager so that they can know that they need to act on the change.
* The example code assumes that the CVE names are available via a text-based search, for example when the respective CVE name is in the defect title or comments. If your system uses a different marker, then you will need to code for that.


* It should create an "Investigation" for each defects, and attach it to the respective product.
<br/>


* It should create a "Vulnerability" to wrap the "Investigation".
== High Level Development Plan ==


* If should find the respective CVE record, and attach that to the created "Vunerability".
{| class="wikitable" style="text-align: left;"
! Release
! Features
! Status/date
|-
|0.80
|Multi-host testing, Django user model, Django 2.x support
|Released (December 2018)
|-
|0.90
|Mapping of CVE-CPE > Packages > Recipes > Product/Release CPEs, Add Releases to Products, modular report definitions
|Under development (January 2019)
|-
|1.00
|General Release
|Under development (February 2019)
|-
|1.10
|Improved CPE/package mapping hueristics, advanced reports
|Under development (March+ 2019)
|-
|2.00
|Add support for importing CVE Checker result
|Under development (November+ 2023)
|-
|}


* If a "Vulnerability" record already exists for the defect;s CVE, then this script should attach the new "Investigation" to that "Vulnerability" record.
<br/>
== SRTool Bugzilla Page ==


  (b) Add the "--update" command
Here is the link to the SRTool Bugzilla Page: [https://bugzilla.yoctoproject.org/buglist.cgi?list_id=609538&bug_status=__all__&query_format=specific&order=relevance%20desc&product=Security%20Response%20Tool SRTool Bugzilla Page]


* This should scan your CVE related defects


* If the matching defect record in the SRTool database does not exist, then treat it like the "--init" command.
<br/>
== SRTool CGIT Page ==


* Update the SRTool defect record with the current defect system state
Here is the link to the CGIT Page: [http://git.yoctoproject.org/cgit/cgit.cgi/srtool SRTool CGIT Page]


* If the defect has changed priority (or any other important state information), consider creating a "Notification" event to the respective manager so that they can know that they need to act on the change.


== Development Workflow ==
<br/>
== SRTool User Page ==


To contribute to the SRTool you will also need authorization to write to the upstream yocto project repository. Contact a member of the SRTool team for details.
Here is the link to the User's Documentation page: [https://wiki.yoctoproject.org/wiki/SRTool_User_Page SRTool UserPage]


1) Download the master branch of the SRTool
  <code> git pull ssh://git@push.yoctoproject.org/srtool && cd srtool </code>


2) Add poky-contrib to the local repository you set up above
<br/>
  <code> git remote add poky-contrib ssh://git@git.yoctoproject.org/poky-contrib </code>
== SRTool Developer Page ==
 
3) Fetch the poky-contrib branches
  <code> git fetch --all </code>
 
4) Start your feature branch off of master, name style of branch is convention, but suggested.
  <code> git checkout -b username/srtool/FeatureOrBug origin/master </code>
 
5) Do Work
 
6) Test the changes.
 
7) Rebase on master. It has probably changed while you were working (unless you are really really fast!)
 
  <code> git rebase origin/master </code>
 
8) Commit your change
 
<strong>NOTE:</strong> The format of the commit message should be like this
 
<pre>
    srtool: <module> <short one line summary>
 
    long(er) description
 
    [YOCTO #0000]
 
    Signed-off-by: First Last <name@domain.com>
</pre>
 
Where YOCTO #0000 is the related bug number if there is one. Signed off by with your git commit -s credentials.
 
9) Push your feature branch to poky-contrib
 
<code> git push -u poky-contrib username/srtool/FeatureOrBug:username/srtool/FeatureOrBug</code>
 
10) Send to the srtool-mailing list:
 
We accept patches on the [https://www.yoctoproject.org/tools-resources/community/mailing-lists Security mailing list] ( yocto-security@yoctoproject.org ) by "git send-email".
 
e.g.
<code>
    $ git send-email HEAD^
</code>
 
11) NOTE: when the patch has been accepted upstream, you can clean up your poy-contrib branch with:
 
  <code> git push -u poky-contrib :username/srtool/FeatureOrBug </code>
 
== Developing the SRTool ==
 
=== Design ===
 
(in progress)
 
=== Data Sources ===
 
(in progress)
 
=== Tables and pages ===
 
(in progress)
 
== Debugging the SRTool ==


The same basic techniques for debugging Toaster also apply to the SRTool. See this link for details [https://wiki.yoctoproject.org/wiki/Contribute_to_Toaster#Debugging_Toaster].
Here is the link to the Developer's page: [https://wiki.yoctoproject.org/wiki/SRTool_Developer_Page SRTool Developer Page]

Latest revision as of 05:59, 30 November 2023

This page summarizes the Security Response Tool (SRTool) development process. We hope this will help you start contributing to the project. The SRTool is based on the Yocto Project Toaster codebase (Django,Python,Javascript), so many of the process and debugging techniques apply.


Published content: General CVE management issues and the SRTool


Set up the local repository and SRTool instance

1) Host requirements

The SRTool should in principle work on any host that supports Yocto Project. It requires "Python3", "Django >= 1.11", and "Sqlite3". A SQL GUI tool like 'sqlitebrowser' is recommended.

The required host package installation instructions are the same as Toaster, and the instructions can be found here: Toaster documentation

It was specifically developed and tested with:

Item Host 1 Host 2 Host 3
Host Ubuntu 20.04
Python3 3.8.10
Django 4.00
Sqlite3 3.31.1


2) Cloning the SRTool

  $ git clone git://git.yoctoproject.org/srtool && cd srtool 

Here is the command if your SSH key is registered:

  $ git clone ssh://git@push.yoctoproject.org/srtool && cd srtool 

3) Starting the SRTool

Option #1: Restrict to the local browser:

  $ ./bin/srt start webport=localhost:9000 

Option #2: Enable remote browsers:

  $ ./bin/srt start webport=0.0.0.0:9000 

NOTE: The first time you run the SRTool, there will be a delay (30 to 60 minutes) as the default CVE repositories (NIST, Mitre, ...) are scanned, scored, and loaded into the database. After that, the updates will be incremental.

4) Create a superuser

You will need to create at least one super user account to promote users to higher permission levels:

  $ ./bin/srt manage createsuperuser 

5) Open browser to <IPADDR>:9000

This will bring up the SRTool page.

6) Read the "Guided Tour"

Click on the "Guided Tour" button on the home page to see the on-line tool and user information.

7) Create your guest account

Click on the "Login" button in the top bar, select "Request Account", fill in the information, Click "Sign Up", and then log in.

8) Promote your account to Admin level

Login as the superuser, click "Management > Manage Users", click the edit icon for your guest account row, change the "Group" to "Admin", and click "Submit Changes".

You can now log out of the superuser account and into your own account.


Sanity Test Bring-up

You can use these steps to start a minimal instance of the SRTool to help validate that the host and the code base are working on your system. This will for example set the environment variable "SRTDBG_MINIMAL_DB=1" which will only fetch a few representative records from each data source.

 $ # Clone the SRTool
 $ git clone git://git.yoctoproject.org/srtool && cd srtool 
 $ # Bring down the development assistance tools
 $ cp bin/dev_tools/* .
 $ # Prepare the venv and SRTool environment variables
 $ . prepare_environment.sh
 $ # Start the SRTool, trigger the CVE downloads
 $ ./restart.sh
 ...
 SRTool webserver started at http://0.0.0.0:9000
 $ # Create the initial superuser account, who can then create all other accounts
 $ ./super.sh 
 SRT_MAIN_APP=yp
 The system will manage.
 Username: srtool
 Email address: 
 Password: 
 Password (again): 
 Superuser created successfully.
 $

Sanity command test:

 $ ./bin/common/srtool_sanity_test.py -i
 * Host statistics ...
 Uname       = #44~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Mon May 22 13:39:36 UTC 2 x86_64
 Django      = (4, 0, 0, 'final', 0)
 Python3     = Python 3.10.12
 Sqlite3     = 3.37.2 2022-01-06
 Server PID  = 95890
 * Database statistics ... (use '-v' for details)
 * Table checks ...
 * Summary ...
 CVEs        = 219524
 Users       = 6
 Data sources= 51
 $ 


First Time Bring-up

  • When you first start, you will have the CVEs from 2015 to 2023
  • You will not have any Vulnerabilities, Investigations, or Defects until you (a) create them, and/or (b) integrate your defect system or other sustaining data.
  • All CVEs will by default get the status "Historical".
    • The CVEs that were created in the previous 30 days will instead get the status "New"
    • This will allow you to immediately test the CVE triage features
    • The status settings are normally preset by your defect system or other sustaining data
  • You can create a Vulnerability by:
    • Selecting a CVE
    • Click on "Create Vulnerability"
    • Follow the new link to the new Vulnerability
  • You can create an Investigation by:
    • Open a Vulnerability record
    • Click on "Add Product"
    • Select one or more Products, and click "Submit"
    • Observe that the products are added together with new respective Investigations
    • Follow the new link to the new Investigations
  • You can create a Defect by:
    • Open an Investigation record
    • Click on "Create Defect"
    • With the sample defect integration script, a simulated defect will be created and attached to the investigation


SRTool Primary Goals and Workflows

  • Goals
    • A common system to track and share security issues, combining community CVE's
    • A simple yet flexible interface for reporting and exploring the security issues
    • A place to upload and share attachments, including patches, fixes, emails, and documents
    • The ability to generate accurate and up-to-date reports and exports
    • A modular design for easy extension and adoption


  • Primary Workflows
    • Guide and manage the incoming CVE triage process
    • Attach CVEs to specific company products and defects
    • Automated updates from upstream CVEs and internal defect system
    • Ability to generate reports
    • Simple customization for organizations
    • Correlate CVEs with products and release (IN PROGRESS)
    • Correlate CVEs with specific customer builds (IN PROGRESS)


SRTool CVE Lifecycle

  • CVE are imported
    • New CVEs are imported and triaged from upstream (NIST/MITRE, 1000+/month)
    • Specific CVEs are requested by customers
  • CVEs are managed
    • CVEs are investigated
    • Vulnerable CVEs are assigned to products via defects
    • SRTool manager tracks the progress of open CVEs
    • SRTool manager produces reports as required by customers, field, and management
  • CVEs are resolved
    • CVEs are either fixed or declared not vulnerable
    • Releases are updated with the CVE fixes
    • Resolved CVEs are reported to customers, public website


Testing the Alternate Sample Organization 'ACME'

  • An example alternate organization (master application) called "acme" is included.
  • This code shows all the ways the SRTool can be easily customized to the needs of your organization
  • To enable it and try it out, do the following:

   $ # Include the quick development tools
   $ cp bin/dev_tools/* .
   $ # Reset 'acme' as the master app/organization
   $ ./stop.sh
   $ ./master_app.sh acme
   $ ./start.sh

  • When you browse the SRTool pages, will now observe several differences
    • In the top bar the text "[ACME]" will appear in several places. This shows how files like "lib/acme/templates/base.html" can take precedence over the default template files in "lib/srtgui".
    • In the top left corner the "ACME" logo will appear. This is from "SRTOOL_LOCAL_LOGO" being defined in "datasource.json".
    • If you click on the ACME logo you will be taken to an ACME hello page. This shows that "lib/acme/urls.py" has extended the URL map, plus how you can implement basic HTML pages in ACME's "lib/acme/views.py" and "lib/acme/templates/acme_hello.html".
    • In the ACME hello page, there are links to custom table pages for Products and Defects. This shows how to implement custom Toaster Tables via "lib/acme/urls.py" and "lib/acme/tables.py"
    • In the Products page, when you click "Export" a new report type "ACME Products Table" is appended. This shows how to extend and customize existing or new reports.
  • To restore the default "yp" master application, do the following:

   $ ./stop.sh
   $ ./master_app.sh yp
   $ ./start.sh

Adapting SRTool to your Organization

  • You can use the sample alternate organization "acme" as a guide to adapt SRTool to your organization
  • In this example, we will instantiate a new organization called "yoyodyne"
  • You should be able to place all of your local content into these two directories:
    • "./bin/yoyodyne": this is your master datasource directory
    • "./lib/yoyodyne": this is your master Django App directory
  • If you find you need to make changes in the core SRTool code, we recommend (in preferential order):
    • See if you can make it a generic feature so that it can become part of the mainline codebase
    • See if you can make an easy hook for the mainline code, so that your custom content can still reside in your directories
    • Talk to us on how to easily have managed custom patches to the mainline code (we do this in Toaster)

1) Instantiate your Organization

You can create a starting customization of the SRTool for your organization with these simple steps.

  • In this example, we will use the name "yoyo" as a shorthand for a mythical "Yoyodyne Corporation".

 $ cd /path_to/srtool_dir
 $ copy bin/dev_tools/* .
 $ ./stop.sh
 $ ./master_app.sh create yoyo
 $ ./start.sh

  • This script will perform the following actions:
    • Copy the sample 'bin/acme' directory to 'bin/yoyo'
    • Copy the sample 'lib/acme' directory to 'lib/yoyo'
    • Rename the respective Acme/ACME/acme labels and filenames to Yoyo/YOYO/yoyo
    • Set 'yoyo' as the new main application
  • You now have access to all the preset custom features described above for the ACME sample organization, now for Yoyodyne.

2) Add your defect system integration

You will need to implement a defect integration backend script to scan your defect system and instantiate the CVE defects in SRTool database, and then keep them up to date.

  • An example implementation template for Jira is provided here.

 bin/common/srtool_jira_template.py

  • You can use this to guide your integration to Jira or to other defect systems.
  • To see how to extend this template to your organization and yet maintain compatibility with upstream, see this section: Extending and customizing common/template code files
  • Please contact the SRTool developers for assistance in your defect system integration effort.

The main features of this example code, in addition to the Jira system access, is:

  • The "--init" command
    • This command that will initialize the SRTool database with your SRT related defects. Specifically, this command can used to bootstrap the SRTool database for your company's data
    • It will create an "Investigation" for each defect, and attach it to the respective product
    • It will create a "Vulnerability" to wrap the respective "Investigation"
    • If should find the respective CVE record if it exists, and attach that to the created "Vulnerability"
    • If a "Vulnerability" record already exists for the defect's CVE, then this script should attach the new "Investigation" to that "Vulnerability" record.
  • The "--update" command
    • This will scan your CVE-related defects
    • If the matching defect record in the SRTool database does not exist, then treat it like the "--init" command.
    • It will update the SRTool defect record with the current defect system state
    • If the defect has changed priority (or any other important state information), it will create a "Notification" event to the respective manager so that they can know that they need to act on the change.
  • The example code assumes that the CVE names are available via a text-based search, for example when the respective CVE name is in the defect title or comments. If your system uses a different marker, then you will need to code for that.


High Level Development Plan

Release Features Status/date
0.80 Multi-host testing, Django user model, Django 2.x support Released (December 2018)
0.90 Mapping of CVE-CPE > Packages > Recipes > Product/Release CPEs, Add Releases to Products, modular report definitions Under development (January 2019)
1.00 General Release Under development (February 2019)
1.10 Improved CPE/package mapping hueristics, advanced reports Under development (March+ 2019)
2.00 Add support for importing CVE Checker result Under development (November+ 2023)


SRTool Bugzilla Page

Here is the link to the SRTool Bugzilla Page: SRTool Bugzilla Page



SRTool CGIT Page

Here is the link to the CGIT Page: SRTool CGIT Page



SRTool User Page

Here is the link to the User's Documentation page: SRTool UserPage



SRTool Developer Page

Here is the link to the Developer's page: SRTool Developer Page