|
|
|
- [_Lazart documentation_](../home)
|
|
|
|
|
|
|
|
This page presents the process of an Analysis inside Lazart and the [`Analysis`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.core.analysis.html#lazart.core.analysis.Analysis) object.
|
|
|
|
|
|
|
|
**Summary:**
|
|
|
|
|
|
|
|
- [Analysis parameters](#analysis-parameters)
|
|
|
|
- [Steps parameters](#steps-parameters)
|
|
|
|
- [Execute function](#execute-module)
|
|
|
|
- [Analysis folder structure](#analysis-folder-structure)
|
|
|
|
- [Going Further](#going-further)
|
|
|
|
|
|
|
|
# Analysis parameters
|
|
|
|
|
|
|
|
The [`lazart.core.Analysis`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.core.analysis.html#lazart.core.analysis.Analysis) type represents an analysis with **Lazart**. It contains all parameters necessary to an analysis.
|
|
|
|
|
|
|
|
An analysis object requires at least the attack model (see corresponding [section](attack-model)) that describes the faults that can be injected by the attackers and the list of input files to be compiled.
|
|
|
|
|
|
|
|
Several optional parameters can be passed and this section list few of them. For a full list of available parameters, please refer to the [documentation](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.core.analysis.html#lazart.core.analysis.Analysis).
|
|
|
|
|
|
|
|
The `path` argument corresponds to the folder in which the results will be saved. This parameter is overridden by `--output-folder` command line argument in scripts. If none is specified, an available empty folder in current directory will be used.
|
|
|
|
|
|
|
|
The `name` argument is only used to display purpose and does not impact the analysis itself. However, it can be useful if you run multiple analysis inside one script.
|
|
|
|
|
|
|
|
The `flags` argument holds the [AnalysisFlag](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.core.analysis.html#lazart.core.analysis.AnalysisFlag) determining which type of analysis should be applied. Utility function such as [`exec`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.util.exec.html#lazart.util.exec.exec) or [`report`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.results.report.html) modules uses those flags to determines which operation and analysis will be applied. Use `AttackAnalysis` for standard attack paths research and `EqRedAnalysis` to enable [equivalence and redundancy](Analysis/Redundancy-and-Equivalence) analysis.
|
|
|
|
|
|
|
|
By default, **Lazart** uses `clang` as compiler. You can change this with the corresponding analysis parameters: `compiler`, `disassembler` and `linker`. Additional option can be pass through the corresponding `compiler_args`, `dis_args` and `linker_args` parameters.
|
|
|
|
|
|
|
|
[Automated countermeasures passes](Countermeasures) are specified with the `countermeasures` argument, and [preprocessing tasks](Mutation-(Wolverine)) (such as `add_trace` and `rename_bb`) are described using the `tasks` argument.
|
|
|
|
|
|
|
|
# Steps parameters
|
|
|
|
|
|
|
|
Analysis are executed using a sequence of steps (see [Lazart's workflow](Core#lazarts-workflow) section):
|
|
|
|
|
|
|
|
1. _compilation and preprocessing_: [`lazart.core.compile.compile_results`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.core.compile.html#lazart.core.compile.compile_results)
|
|
|
|
2. _mutation_: [`lazart.core.run.run_results`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.core.run.html#lazart.core.run.run_results)
|
|
|
|
3. _concolic execution_: [`lazart.core.run.run_results`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.core.run.html#lazart.core.run.run_results)
|
|
|
|
4. _traces parsing_: [`lazart.core.traces.traces_results`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.core.run.html#lazart.core.traces.traces_results)
|
|
|
|
5. _analysis steps_: [`lazart.analysis`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.analysis.html)
|
|
|
|
|
|
|
|
Each step can have specific parameters that can be specified when calling the corresponding function or with the call of `execute` function (see next section)
|
|
|
|
|
|
|
|
The following analysis are provided by Lazart:
|
|
|
|
|
|
|
|
- [Attack analysis](Analysis/Attack-Analysis).
|
|
|
|
- [Hotspots analysis](Analysis/Hotspot-Analysis).
|
|
|
|
- [Equivalence and redundancy analysis](Analysis/Redundancy-and-Equivalence).
|
|
|
|
- Detector Optimization (not documented).
|
|
|
|
- Placement analysis (not documented).
|
|
|
|
|
|
|
|
# Execute module
|
|
|
|
|
|
|
|
The [lazart.util.exec](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.util.exec.html) provides the [`execute`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.util.exec.html#lazart.util.exec.execute) that executes each step depending on the specified [`AnalysisFlag`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.core.analysis.html#lazart.core.analysis.AnalysisFlag). For instance, using [`AnalysisFlag.EqRedAnalysis`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.core.analysis.html#lazart.core.analysis.AnalysisFlag.EqRedAnalysisOnly), the call to [`execute`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.util.exec.html#lazart.util.exec.execute) corresponds to :
|
|
|
|
|
|
|
|
```py
|
|
|
|
compile_results(a) # Compilation.
|
|
|
|
run_results(a) # Mutation and DSE.
|
|
|
|
traces_results(a) # Gathering traces information from KLEE's ktests.
|
|
|
|
attacks_results(a) # Computing attacks analysis.
|
|
|
|
attacks_redundancy_results(a) # Computing attacks equivalence and redudancy.
|
|
|
|
print_results(a) # Prints results of analysis.
|
|
|
|
generate_reports(a) # Generate analysis reports files.
|
|
|
|
save(a) # Save analysis
|
|
|
|
```
|
|
|
|
|
|
|
|
The steps's keyword arguments are forwarded by the function [`execute`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.util.exec.html#lazart.util.exec.execute).
|
|
|
|
|
|
|
|
# Analysis folder structure
|
|
|
|
|
|
|
|
An analysis folder is structured as follows:
|
|
|
|
|
|
|
|
- `.lazart/`: contains _Lazart_'s data structure allowing to read the analysis without re-computation.
|
|
|
|
- _mutation files_:
|
|
|
|
- `main.bc`: studied program LLVM bytecode.
|
|
|
|
- `main.ll`: text version of `main.bc`.
|
|
|
|
- `preprocessed.bc`: mutated bytecode after preprocessing.
|
|
|
|
- `countermeasures.bc`: mutate bytecode after preprocessing including countermeasure application.
|
|
|
|
- `mutated.bc`: mutated bytecode after complete mutation.
|
|
|
|
- `mutated.ll`: text version of `mutated.bc`.
|
|
|
|
- `injection_points.yaml`: YAML file of data for all IPs inside the mutated module.
|
|
|
|
- `ccp_list.yaml`: YAML file of data for all detectors inside the mutated module.
|
|
|
|
- `dse_out/`: _Klee_'s .ktest files (if the option \`\` is specified).
|
|
|
|
- `replay`: mutated LLVM bytecode including **KLEE**'s replay functions.
|
|
|
|
- `am.yaml`: YAML attack model for Wolverine (copied from user's specified one or generated by Python API).
|
|
|
|
- _results_:
|
|
|
|
- `report.md`: analysis report.
|
|
|
|
- `results`: binary containing the [`Metric`](https://lazart.gricad-pages.univ-grenoble-alpes.fr/lazart/python-api/lazart.results.results.html#lazart.results.Metric) object of the analysis.
|
|
|
|
- `res.csv`: CSV file of all metrics.
|
|
|
|
- `aar.csv`: CSV file of [Attack Analysis](Analysis/Attack-Analysis) and [Redundancy and Equivalence](Analysis/Redundancy-and-Equivalence) results.
|
|
|
|
- `hs.csv`: CSV file of [Hotspots Analysis](Hotspot-Analysis) results.
|
|
|
|
- `graphs/`: contains generated graphs (attacks, redundancy, detectors etc.).
|
|
|
|
- `logs`: Wolverine logs for the analysis (with full verbosity).
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
# Going Further
|
|
|
|
|
|
|
|
- [Metrics and results](Analysis/Metrics-and-results): describes how get and modify the metrics provided by Lazart.
|
|
|
|
- [Attack Model](Attack-Model): describe how the attack model is specified in Lazart.
|
|
|
|
- [Countermeasures](Countermeasures): automated countermeasures application in Lazart and
|
|
|
|
- [Mutation (Wolverine)](Mutation-(Wolverine)).
|
|
|
|
- [Traces](Core/Traces).
|
|
|
|
- [User scripts](Environement/User-Scripts). |
|
|
\ No newline at end of file |
