Globalyzer Lite Project Definition Files

Overview

A Project Definition XML File specifies the following information for Globalyzer Lite:

  • Login information.
  • Project information.
  • Report information.
  • A list of scans to perform.
    • Configuration details for each scan.

Globalyzer Lite will read in this file and perform the scans defined in it. It uses an in-memory database, so it will not save any of its state between executions. This means that you'll be getting a fresh look with each scan. The rule sets are created and stored on the server side, so these persist between executions.

Globalyzer Lite also has command line options. When these are specified, they supersede the entries in the Project Definition File. The entries which can have command line options are specified below.

For more examples on how to use the Project Definition file and Globalyzer Lite with and without command line options, see here.


Simple XML Template

Here is a simple Project Definition File template. It contains the minimum settings required to run Globalyzer Lite. 


    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <!-- All items are allowed anywhere in the xml as long as the hierarchy
            is preserved -->
    <gzproject>
        <login>
            <server>https://www.globalyzer.com/gzserver</server>
            <username>demo@lingoport.com</username>
            <password>demopass</password>
        </login>

        <project-path>/home/username/workspace/acme_supplies</project-path>
        <project-name>ACME Supplies</project-name>

        <report-path>LingoportReports</report-path>
        <report-type>ScanDetailedXML</report-type>
        <report-priorities>C,1,2</report-priorities>

        <scans>
            <scan>
                <!-- create and execute a single scan with this info -->
                <scan-name>Java Scan Name</scan-name>
                <ruleset-name>Company Java Base</ruleset-name>
                <ruleset-owner>user@company.com</ruleset-owner>
            </scan>
        </scans>
    </gzproject>

Note that some of these options may instead be specified as command line options, or placed inside a .globalyzerrc file. This file may be compressed even further. See below for details on which options are specifiable elsewhere.



Full XML Template

Below is a template project definition file with all possible options shown. Each option will be discussed at length later on. 


<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- All items are allowed anywhere in the xml as long as the
     hierarchy is preserved -->
<gzproject>
    <login>
        <server>  </server>    <!-- must match .globalyzerrc setting   -->
        <username></username>  <!-- must be specified in .globalyzerrc -->
        <password></password>  <!-- must be specified in .globalyzerrc -->
                               <!--    if .globalyzerrc is present     -->
        <use-local-rulesets></use-local-rulesets>  <!-- optional. May be 'true' or 'false'     -->
                                                   <!-- if true, you need a Globalyzer.license -->
        <!-- Optional Parameters (Delete this section if not using them) -->
        <optional>
            <!-- If using, host and port must be filled out -->
            <proxy-user>    </proxy-user>
            <proxy-password></proxy-password>
            <proxy-host>    </proxy-host>  <!-- required if using proxy -->
            <proxy-port>    </proxy-port>  <!-- required if using proxy -->
        </optional>
    </login>

    <!-- Paths may be absolute, or relative -->
    <project-path></project-path> <!-- may be specified via command line -->
    <project-name></project-name>

    <report-path></report-path>   <!-- may be specified via command line -->
    <report-type></report-type>   <!-- See 'Report Information' -->
    <report-priorities></report-priorities>   <!-- optional. List of priorities to include in reports -->

    <data-dictionary-location></data-dictionary-location> <!-- optional -->
    <filter-with-dictionary></filter-with-dictionary> <!-- optional. May be 'true' or 'false' -->

    <scan-timeout>500</scan-timeout>  <!-- optional. Max value 600 (seconds) -->
    <generate-partial-results></generate-partial-results> <!-- optional. May be 'true' or 'false' -->
    <save-history></save-history> <!-- optional. May be 'true' or 'false' -->


    <scans>
        <scan>
            <!-- create and execute a single scan with this info -->
            <scan-name>    </scan-name>
            <ruleset-name> </ruleset-name>  <!-- must match existing -->
            <ruleset-owner></ruleset-owner>
        </scan>
        <scan>
            <!-- create and execute a single scan with this info -->
            <scan-name>    </scan-name>
            <ruleset-name> </ruleset-name>  <!-- must match existing -->
            <ruleset-owner></ruleset-owner>
            <!-- optional -->
            <use-machine-learning>true</use-machine-learning> <!-- May be 'true' or 'false'         -->
                                                              <!-- if true, you must have generated --> 
                                                              <!-- machine learning zip files       -->
                                                              <!-- from the Workbench               -->
            <!-- optional -->
            <encoding>UTF-8</encoding> <!-- encoding of files to scan -->
            <!-- optional -->
            <scan-items>         <!-- may be overridden via command line -->
                <item></item>    <!-- delete me if blank -->
                <item></item>    <!-- delete me if blank -->
            </scan-items>
            <!-- optional -->
            <comments>
                <!-- customize Globalyzer recognized comments -->
                <todo>SPECIAL_GLOBALYZER_TODO_COMMENT</todo>
                <ignore-next-line>GBLYZR_IGNORE_NEXT_LINE</ignore-next-line>
                <start-ignore>GLOBALYZER_START_IGNORE</start-ignore>
                <end-ignore>GBL_END_IGNORE</end-ignore>
            </comments>
            <!-- optional -->
            <checks>
              <!-- specify which issue types to detect -->
              <embedded-strings>true</embedded-strings>
              <locale-sensitive-methods>false</locale-sensitive-methods>
              <general-patterns>true</general-patterns>
              <static-file-references>false</static-file-references>
            </checks>
        </scan>
    </scans>
</gzproject>


The .globalyzerrc File

Optionally, you may specify your username, password, server-url and proxy settings in a .globalyzerrc file. This file must be saved to your home directory. The username and password will become defaults, but may be overridden by settings specified in the project definition file.

Note: If using a .globalyzerrc, username, password, and server are required; additionally, the server setting in the rc file must always match the setting in the project definition file. This is designed as insurance against retrieving similarly named rule sets from the wrong server.

Example .globalyzerrc (all settings set): 

server https://www.globalyzer.com/gzserver

username user@company.com
password aPasswordHere

proxy-host https://internalhost.company.com
proxy-port 81038
proxy-user ExampleUser
proxy-password ExamplePassword

You may also set settings 'proxy-user'



Login information

The login information includes the following:


<login>
    <server>  </server>    <!-- must match .globalyzerrc setting   -->
    <username></username>  <!-- must be specified in .globalyzerrc -->
    <password></password>  <!-- must be specified in .globalyzerrc -->
                           <!--    if .globalyzerrc is present     -->
    <use-local-rulesets></use-local-rulesets>  <!-- optional. May be 'true' or 'false'     -->
                                               <!-- if true, you need a Globalyzer.license -->
    <!-- Optional Parameters (Delete this section if not using them) -->
    <optional>
        <!-- If using, host and port must be filled out -->
        <proxy-user>    </proxy-user>
        <proxy-password></proxy-password>
        <proxy-host>    </proxy-host>  <!-- required if using proxy -->
        <proxy-port>    </proxy-port>  <!-- required if using proxy -->
    </optional>
</login>
  • A Lingoport username associated with the rule sets on the server.
    • May instead be specified in a .globalyzerrc file in your home directory.
  • A password for the given username.
    • May instead be specified in a .globalyzerrc file in your home directory.
  • The server where you have your rule sets.
    • If you use a .globalyzerrc, the server is still mandatory. It must match the .globalyzerrc set server.
  • Use Local Rulesets if you want to scan your code without accessing the Globalyzer Server.
    • If using local rule sets, you do not need to specify username/password/server information in your Project Definition File.
    • If using local rule sets, but a local rule set is not found and login information is available, Globalyzer will try to access the rule set on the server.
    • Local rule sets are exported zip files that reside in your project-path/lingoport directory.
    • Rule sets can be exported from the server and copied to your project-path/lingoport directory.
    • Rule sets can be exported from the client as an option when exporting your Workbench project to a Globalyzer Lite Project Definition File.
    • Using local rule sets requires a Globalyzer.license file, which can be downloaded from the Globalyzer Server. Place this license file in the following default locations, per OS:
      • Windows - C:\Lingoport
      • Linux - {userhome}/lingoport
      • Mac - /Applications/Lingoport
  • The following optional proxy settings (proxy-host and proxy-port are mandatory if using these):
    • A proxy user.
    • A proxy password.
    • A proxy host.
    • A proxy port.

NOTE:If you are concerned with storing a the password within the XML file, you may instead place it in a '.globalyzerrc' file within your home directory. If on a Unix like filesystem (Linux, OSX), you can set the file's permission to be only accessible by you. E.g. `chmod 600 ~/.globalyzerrc`

Example login specification:


<login>
    <>user@company.com</username>
    <server>https://www.globalyzer.com/gzserver</server>
    <!-- <password></password> (specified in .globalyzerrc) -->
    <!-- server matches .globalyzerrc setting -->
    <optional>
        <!-- <proxy-user>not set</proxy-user>         -->
        <!-- <proxy-password>not set</proxy-password> -->
        <proxy-host>company.proxy.com</proxy-host>
        <proxy-port>12345</proxy-port>
    </optional>
</login>


Project Information

The project information includes a project path and name:


<project-path></project-path>  <!-- Optional, may be overwritten by command line input -->
<project-name></project-name>
  • Project path.
    • The path to the project that you wish to scan.
    • Placing this within the Project Definition file is optional. It may be specified (or overwritten) through command line input.
  • Project name.
    • The name of this project.

Example project information:


<project-path>/home/coyote/sourcecode/acme_company/international_coyote_supplies</project-path>
<project-name>InternationalCoyoteSupplies</project-name>

Report Information

This information is relevant to generated scan reports. The values identify the path, report type, and priorities to include in the generate report.


<report-path></report-path>	 <!-- Optional, may be overwritten by command line input -->
<report-type></report-type>
<report-priorities></report-priorities>

  • Report path.
    • The relative location where you want to place your scan reports.
    • Specifying this within the Project Definition file is optional. It may be set (or overwritten) via command line input.
  • Report type.
    • Must be one of the following, more info here:
    • AggregateDetailedExcel
      • Detailed project report, Excel format.
    • AggregateSummaryExcel
      • Summary project report, Excel format.
    • ScanDetailedCSV
      • Detailed scan report, CSV format.
      • Enables support for console output within IDEs.
    • ScanDetailedXML
      • Detailed scan report, XML format.
      • Enables support for console output within IDEs.
    • ScanDetailedExcel
      • Detailed scan report, Excel format.
    • ScanSummaryHtml
      • Summary scan report, HTML format.
    • ScanSummaryText
      • Summary scan report, plain text format.
  • Report priorities.
    • A comma-separated list of priorities to include in scan reports; for example: C,1,2,3,4,5
    • Specifying this within the Project Definition file is optional.
    • Blank or missing report-priorities attribute results in all priorities included in report.
    • To limit reports to only include issues with priority one, configure: 1

Example report information:


<report-path>globalyzer-lite-reports</report-path>
<report-type>ScanDetailedXML</report-type>
<report-priorities>C,1,2</report-priorities>

This will put the reports in:

/home/coyote/sourcecode/acme_company/international_coyote_supplies/globalyzer-lite-reports

using the project path defined above and the report-path globalyzer-lite-reports.

Additionally, the reports will only include results with priority C, 1, or 2.


NOTE: If you are using the Project Definition file with an IDE, the only supported values for report type are ScanDetailedCSV and ScanDetailedXML.



Globalyzer Dictionary Settings

Globalyzer Lite uses and internal dictionary to filter its results. By default this dictionary is written to '$HOME/.globalyzer/dict'. You can disable use of the dictionary, or write it to a different location.


<filter-with-dictionary></filter-with-dictionary>  <!-- Optional, may be overwritten by command line input -->
<data-dictionary-locaton></data-dictionary-locaton>	 <!-- Optional, may be overwritten by command line input -->
  • Filter With Dictionary
    • Whether or not to use Globalyzer Lite's inbuilt dictionary to filter issues.
    • If no dictionary is used, then Globalyzer Lite will not be able to filter issues based on whether or not they contain dictionary words. However words not in the dictionary (E.g. non english words) will not be subject to this filter.
  • Data Dictionary Location
    • By default, Globalyzer Lite writes its internal dictionary information to $HOME/.globalyzer
    • Using this option, you may tell Globalyzer Lite to write its dictionary to a different location
    • A 'dict' directory is created within this location. E.g. '$HOME/.globalyzer/dict'


Globalyzer Scan Settings

These are global scan settings that affect all scans.


<scan-timeout>500</scan-timeout>  <!-- optional. Max value 600 (seconds) -->
<generate-partial-results></generate-partial-results> <!-- optional. May be 'true' or 'false' -->
<save-history></save-history> <!-- optional. May be 'true' or 'false' -->
  • Scan Timeout
    • Globalyzer sets a timer each time it scans a file and will fail the file scan it if takes longer than the set time.
    • The time specified is in seconds. Default is 120 seconds (2 minutes).
    • The max allowed set time is 600 seconds (10 minutes).
  • Generate Partial Results
    • Typically, a Globalyzer scan involves several files.
    • If there is a scanning error (a timeout) on one of the files, a value of true will continue scanning other files and generate a report with partial results.
    • The default course of action is to fail the entire scan if one file cannot successfully be scanned and to not generate a report.
  • Save History
    • Lite can send Scan History and Login information to the server.
    • The default is false.


List of Scans to Perform

This list specifies the details of all scans that are to be run. There is no limit to the number of scans that may be run, however running a large number of scans can take a significant amount of time.

You must give each scan a unique name and associate it with a rule set. Optionally, you may specify the directories or files to scan by including them as scan items. If these are not defined, then all files within the project path will be scanned.


<scans>
  <scan>
    <!-- create and execute a single scan with this info -->
    <scan-name></scan-name>
    <ruleset-name></ruleset-name>
    <ruleset-owner></ruleset-owner>
    <!-- perform this scan on all files -->
  </scan>

  <scan>
    <!-- create and execute a single scan with this info -->
    <scan-name></scan-name>
    <ruleset-name></ruleset-name>
    <ruleset-owner></ruleset-owner>
    <!-- optional -->
    <!-- perform this scan on only the following files and directories -->
    <scan-items>
      <item></item>
      <item></item>
    </scan-items>
  </scan>

  <scan>
    <!-- create and execute a single scan with this info -->
    <scan-name></scan-name>
    <ruleset-name></ruleset-name>
    <ruleset-owner></ruleset-owner>
    <scan-items>
      <item></item>
    </scan-items>
    <comments>
      <ignore-next-line></ignore-next-line>
      <start-ignore></start-ignore>
      <end-ignore></end-ignore>
    </comments>
    <encoding></encoding>
    <checks>
      <embedded-strings></embedded-strings>
      <locale-sensitive-methods></locale-sensitive-methods>
      <general-patterns></general-patterns>
      <static-file-references></static-file-references>
    </checks>
  </scan>
</scans>

  • Scan - The stanza for a single scan using a rule set
    • Scan name - A unique name for the given scan.
    • Rule set name - Name of the rule set on the server associated with this scan.
    • Rule set owner - The owner on the Globalyzer server of the supplied rule set.
    • (Optional) Encoding - Encoding used to read files. Defaults to the java system default encoding.
  • Optional Scan Sections
    • Scan Items
      • Item(s)- File(s) and/or directories to be scanned.
    • Encoding
      • Specify encoding of the source fields. Default setting is 'systemDefault'.
    • Comments - Change which comments Globalyzer Lite looks for in source code.
      • Todo: Specify what in-file comment marks issues as 'TODO'. Default 'GLOBALYZER_TODO'.
      • Ignore Next Line: Specify what in-file comment tells Globalyzer to ignore the following line. Default 'GLOBALYZER_IGNORE_NEXT_LINE'.
      • Start Ignore: Specify what in-file comment tells Globalyzer to begin ignoring all issues in a section. Default 'GLOBALYZER_START_IGNORE'.
      • End Ignore: Specify what in-file comment tells Globalyzer to stop ignoring all issues in a section. Default 'GLOBALYZER_END_IGNORE'.
    • Checks - Determine which issue types Globalyzer Lite scans for.
      • Embedded Strings: true/false. Should Globalyzer Lite scan for embedded string related issues?
      • Locale Sensitive Methods: true/false. Should Globalyzer Lite scan for locale sensitive methods.
      • General Patterns: true/false. Should Globalyzer Lite scan for miscellaneous programming language specific i18n issues?
      • Static File References: true/false. Should Globalyzer Lite scan for source code links to files which may contain locale sensitive content?

Example scan information:


<scans>
  <scan>
    <!-- create and execute a single scan with this info -->
    <scan-name>ACME_Java</scan-name>
    <ruleset-name>ACME Java Rule Set</ruleset-name>
    <ruleset-owner>employee.email@acme.com</ruleset-owner>
    <!-- perform this scan on all files -->
  </scan>

  <scan>
    <!-- create and execute a single scan with this info -->
    <scan-name>ACME Javascript</scan-name>
    <ruleset-name>ACME Javascript Rule Set</ruleset-name>
    <ruleset-owner>employeer.email@acme.com</ruleset-owner>
    <!-- optional -->
    <!-- perform this scan on only the follow files and directories -->
    <scan-items>
      <item>src/main/webapp/js</item>
      <item>src/main/webapp/static/js</item>
    </scan-items>
  </scan>

  <scan>
    <!-- create and execute a single scan with this info -->
    <scan-name>Java Basic</scan-name>
    <ruleset-name>Java Ruleset</ruleset-name>
    <ruleset-owner>masnes@lingoport.com</ruleset-owner>
    <scan-items>
      <item>src/main/java</item>
    </scan-items>
    <!-- New fields. All new fields are optional -->
    <comments>
      <todo>SPECIAL_COMMENT</todo>
      <ignore-next-line>IGNORELINE</ignore-next-line>
      <start-ignore>STARTIGNORE</start-ignore>
      <end-ignore>ENDIGNORE</end-ignore>
    </comments>
    <encoding>UTF-8</encoding>
    <checks>
      <embedded-strings>false</embedded-strings>
      <static-file-references>true</static-file-references>

      <!-- The following default to false because at least one issue is set to 'true' -->

      <!-- <general-patterns></general-patterns>  -->
      <!-- <locale-sensitive-methods></locale-sensitive-methods>  (Defaults to false)-->
    </checks>
  </scan>
</scans>