forked from KdmAnalytics/toif
-
Notifications
You must be signed in to change notification settings - Fork 0
/
INSTALL
176 lines (117 loc) · 8.42 KB
/
INSTALL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
//////////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2013 KDM Analytics, Inc. All rights reserved. This program and the
// accompanying materials are made available under the terms of the Open Source
// Initiative OSI - Open Software License v3.0 which accompanies this
// distribution, and is available at http://www.opensource.org/licenses/osl-3.0.php/
//////////////////////////////////////////////////////////////////////////////////
http://kdmanalytics.com
ADAPTORS
============
Required Generator Versions:
Cppcheck 1.40
Findbugs 1.3.9
Jlint 3.0
Rats 2.3
Splint 3.1.2
--------------------------------------------------------------------------------------------------------------------
Configuration:
In order to run the adaptors, there is some configuration that will be required. It is essential that the required vulnerability detection tools are pre-installed and have been added to path. Ensure that you are using an adaptor that is compatible with the version of your generator. Using a more recent generator than the adaptor is designed for, may result in missing CWE's, SFP's, and Clusters.
House Keeping:
Because the TOIF output provides information relating to the parties and tools involved in the analysis of a project, this information must be entered into a file and handed to the Adaptor as an argument. The text file is a map of keys and values. The keys relate to facts and entities used in the project, while the values are information about that particular fact or entity. It is imperitive that this information is included. It is recomended that you follow this example.
House Keeping Example:
###########################
# Facts
###########################
TOIFSegmentIsRelatedToProject=project1
TOIFSegmentIsProducedByOrganization=org1
TOIFSegmentIsOwnedByOrganization=org1
TOIFSegmentIsGeneratedByPerson=person1
TOIFSegmentIsSupervisedByPerson=person1
PersonIsInvolvedInProjectAsRole=person1;project1;role1
OrganizationIsInvolvedInProjectAsRole=org1;project1;role2
OrganizationIsPartOfOrganizationAsRole=org1;org2;role2
PersonIsEmployedByOrganizationAsRole=person1;org1;role1
###########################
# Entities
###########################
SegmentDescription=Segment relating to the findings on the wireshark project.
#projectId=name;description
project1=Wireshark;Using Wireshark to test the TOIF tool chain.
#personId=name;email;phone
person1=Adam Nunn;[email protected];555-1234
#person2=Joe Bloggs;[email protected];555-1234
#organizationId=name;description;address;phone;email
org1=KDM;Kdm Analytics;Richmond Road;555-5555;[email protected]
#organizationId=name;description;address;phone;email
org2=Acme Corporation;Acme Corporation;blah;555-5555;[email protected]
#roleId=name;description
role1=Software Developer;Developer on the TOIF Adaptors project
role2=company;employer
--------------------------------------------------------------------------------------------------------------------
Running the Adaptor from command line:
The adaptor is run from the command line. Which adaptor to use with the framework is included in the arguments.
toif --adaptor=<Adaptor Name> --inputfile=<full path to input file> --outputdirectory=<path to output directory> --houseKeeping=<path to house-keeping file> [Additional arguments]
“--adaptor”
The name of the adaptor class. This is usually the name of the adaptor jar file without the version number. This is the adaptor that is to be used with the input source file. From this class, the framework is able to discover house keeping facts about the adaptor as well as which generator to call and what options to use.
“--inputFile”
The full path to the input source file. In order for the adaptors to create all the facts for this file, a full path must be provided
“--outputDirectory”
The path to the output directory. This is the directory where the subdirectories containing the TOIF XML file will be written.
“--houseKeeping”
The path to the file containing the facts about the project's house keeping. This file is specific to each adaptor and each project. This is because it is down to the user to provide the project details as well as which generator (scan tool) is running on the system.
Any additional arguments may be entered after the ToifAdaptor's required arguments. These may be included files or compilation options, they will vary from generator to generator.
eg splint takes -I and -D options:
java -cp "/home/user/adaptors/*" ToifAdaptor -a SplintAdaptor -i /home/user/foo.c -o /home/user/output -h housekeepingFile.txt -I./includes -D_U_=
--------------------------------------------------------------------------------------------------------------------
Integrating with a C project's build:
The best way to integrate the adaptors into the build, is by wrapping the compiler and the adaptors into a script. When the compiler is called, the adaptors will be run for every source file used. To get the build process to use this wrapper instead of the compiler on its own, the compiler flag needs to be set during configuration of the make:
./configure CC=myGccWrapper
The make can then be continued as normal:
make
make install
--------------------------------------------------------------------------------------------------------------------
Integrating with Java project build:
It may be possible to integrate into a Java project's build by modifying Apache Ant's “build.xml” file. Create a new target which will find all the “.class” files in the destination directory of the project. For each file, the javaAdaptors script will be run with the arguments that are specified:
<target name="check" depends="compile_src">
<foreach param="file" target="run">
<path>
<fileset dir="${classes_dir}">
<filename name="**/*.class" />
</fileset>
</path>
</foreach>
</target>
<target name="run" >
<exec executable="python">
<arg value="C:/Users/user/javaAdaptors.py"/>
<arg value="${file}"/>
<arg value="${build_dir}"/>
</exec>
</target>
To run the adaptors and compile the project, the following command should be given:
ant check
--------------------------------------------------------------------------------------------------------------------
Validation:
Validation of the ouput of the TOIF tool can be performed with xmllint.
xmllint --noout --schema <location of the toif schema> <toif file to validate>
Note: xmllint accepts the "*" to validate more than one file at a time.
--------------------------------------------------------------------------------------------------------------------
ASSIMILATOR
============
The assimilator merges TOIF findings into a common fact-orientated repository or file.
--------------------------------------------------------------------------------------------------------------------
To run the assimilator, execute the assimilator script on the command line, specifying the repository location and the files to merge.
assimilator.sh -k <path to repository> <files or directories to merge>
-k used to specify a output .kdm file.
--------------------------------------------------------------------------------------------------------------------
REPORT VIEW
============
Report views allow you to view the toif findings in eclipse.
--------------------------------------------------------------------------------------------------------------------
The UpdateSite.zip file can be used like a regular updatesite in eclipse. When installing new software from the help menu, "Add" the UpdateSite.zip as an archive and follow the regular eclipse-plugin process.
Kdm files should be imported via right clicking on the project, selecting "Import" -> "SFP/CWE" -> "Import integrated SFP/CWE File". The project will then need to be selected and the kdm file choosen from the browse buton.
You can then go "Project" -> "SFP/CWE" -> "(Re)Build Defect model".
Known Issuse:
The trace back currently shows numbers as reported by the toif adaptors unlike the code locations in the views list (which are normalized to kdm locations).
Before "(Re)Build Defect Model" is used on a different project, the toif view should be closed.