Merge pull request #38 from Kretchen001/37-code-documentation

37 code documentation

code/AmIVulnerable/AmIVulnerable/Controllers/DbController.cs

@@ -13,6 +13,10 @@ namespace AmIVulnerable.Controllers {
     [ApiController]
     public class DbController : ControllerBase {
 
+        /// <summary>
+        /// Get-route checking if raw cve data is in directory
+        /// </summary>
+        /// <returns>OK, if exists. No Content, if doesnt exist</returns>
         [HttpGet]
         [Route("CheckRawDir")]
         public IActionResult IsRawDataThere() {
@@ -26,6 +30,10 @@ public IActionResult IsRawDataThere() {
             }
         }
 
+        /// <summary>
+        /// Get-route converting raw cve data to db data
+        /// </summary>
+        /// <returns>OK if successful</returns>
         [HttpGet]
         [Route("ConvertRawDirToDb")]
         public IActionResult ConvertRawFile() {
@@ -34,6 +42,7 @@ public IActionResult ConvertRawFile() {
             string path = $"{AppDomain.CurrentDomain.BaseDirectory}raw";
             ExploreFolder(path, fileList);
 
+            //filter for json files
             foreach (int i in Enumerable.Range(0, fileList.Count)) {
                 if (!Regex.IsMatch(fileList[i], @"CVE-[-\S]+.json")) {
                     indexToDelete.Add(i);
@@ -51,6 +60,11 @@ public IActionResult ConvertRawFile() {
             return Ok();
         }
 
+        /// <summary>
+        /// Adds file names of all files of a folder and its subfolders to a list
+        /// </summary>
+        /// <param name="folderPath">path to target folder</param>
+        /// <param name="fileList">list of files</param>
         private static void ExploreFolder(string folderPath, List<string> fileList) {
             try {
                 fileList.AddRange(Directory.GetFiles(folderPath));
@@ -64,6 +78,13 @@ private static void ExploreFolder(string folderPath, List<string> fileList) {
             }
         }
 
+        /// <summary>
+        /// Check for an cve entry of a package with all its versions
+        /// </summary>
+        /// <param name="packageName">Name of package to search</param>
+        /// <param name="isDbSearch">true: search db, false: search raw-json</param>
+        /// <param name="packageVersion">Version of package to search</param>
+        /// <returns>Ok with result. NoContent if empty.</returns>
         [HttpPost]
         [Route("checkSinglePackage")]
         public IActionResult CheckSinglePackage([FromHeader] string packageName,
@@ -94,6 +115,11 @@ public IActionResult CheckSinglePackage([FromHeader] string packageName,
             return Ok();
         }
 
+        /// <summary>
+        /// Search package in raw-json data
+        /// </summary>
+        /// <param name="packageName">Name of package to search</param>
+        /// <returns>List of CveResults</returns>
         private List<CveResult> SearchInJson(string packageName) {
             List<string> fileList = new List<string>();
             List<int> indexToDelete = new List<int>();
@@ -135,6 +161,11 @@ private List<CveResult> SearchInJson(string packageName) {
             return results;
         }
 
+        /// <summary>
+        /// Search for a list of packages
+        /// </summary>
+        /// <param name="packages">List of tuple: package, version</param>
+        /// <returns>OK, if exists. OK, if no package list searched. NoContent if not found.</returns>
         [HttpPost]
         [Route("checkPackageList")]
         public async Task<IActionResult> CheckPackageListAsync([FromBody] List<Tuple<string, string>> packages) {

code/AmIVulnerable/AmIVulnerable/Controllers/DependeciesController.cs

@@ -13,6 +13,11 @@ namespace AmIVulnerable.Controllers {
     [ApiController]
     public class DependeciesController : ControllerBase {
 
+        /// <summary>
+        /// Extract dependecies of different project types as json
+        /// </summary>
+        /// <param name="projectType">Type of project to extract dependencies from</param>
+        /// <returns>OK if known project type. BadRequest if unknown project type.</returns>
         [HttpGet]
         [Route("ExtractTree")]
         public IActionResult ExtractDependencies([FromHeader] ProjectType projectType) {
@@ -30,6 +35,11 @@ public IActionResult ExtractDependencies([FromHeader] ProjectType projectType) {
             }
         }
 
+        /// <summary>
+        /// Extract dependecies of different project types as json and extract resulting dependency trees of vulnerabilities
+        /// </summary>
+        /// <param name="projectType">Type of project to extract dependencies from</param>
+        /// <returns>OK if vulnerability found. 299 if no vulnerability found. BadRequest if unknown project type is searched.</returns>
         [HttpGet]
         [Route("ExtractAndAnalyzeTree")]
         public async Task<IActionResult> ExtractAndAnalyzeTreeAsync([FromHeader] ProjectType projectType) {
@@ -53,6 +63,11 @@ public async Task<IActionResult> ExtractAndAnalyzeTreeAsync([FromHeader] Project
             }
         }
 
+        /// <summary>
+        /// Starts a process that runs a command.
+        /// </summary>
+        /// <param name="prog">Programm used for commands</param>
+        /// <param name="command">Command used for programm</param>
         private void ExecuteCommand(string prog, string command) {
             ProcessStartInfo process = new ProcessStartInfo {
                 FileName = "cmd",
@@ -65,6 +80,11 @@ private void ExecuteCommand(string prog, string command) {
             runProcess.WaitForExit();
         }
 
+        /// <summary>
+        /// Extracts a tree from node project
+        /// </summary>
+        /// <param name="filePath">File path to rawAnalyze/tree.json</param>
+        /// <returns>List of vulnerable packages.</returns>
         private List<NodePackage> ExtractTree(string filePath) {
             List<NodePackage> packages = [];
             using (JsonDocument jsonDocument = JsonDocument.Parse(F.ReadAllText(filePath))) {
@@ -80,6 +100,11 @@ private List<NodePackage> ExtractTree(string filePath) {
             return packages;
         }
 
+        /// <summary>
+        /// Extracts dependencies of a single dependency.
+        /// </summary>
+        /// <param name="dependency">Dependency that is searched for sundependencies and versions.</param>
+        /// <returns>NodePackage with all found dependencies and versions.</returns>
         private NodePackage ExtractDependencyInfo(JsonProperty dependency) {
             NodePackage nodePackage = new NodePackage {
                 Name = dependency.Name
@@ -99,7 +124,12 @@ private NodePackage ExtractDependencyInfo(JsonProperty dependency) {
             return nodePackage;
         }
 
-        private async Task<List<NodePackageResult?>?> analyzeTreeAsync(List<NodePackage> depTree) {
+        /// <summary>
+        /// Analyse list of node packages, compare dependencies of each with cve and return list of NodePackageResult
+        /// </summary>
+        /// <param name="depTree">List of all top level node packages.</param>
+        /// <returns>List of NodePackageResult.</returns>
+        private async Task<List<NodePackageResult?>> analyzeTreeAsync(List<NodePackage> depTree) {
             List<Tuple<string, string>> nodePackages = [];
             // preperation list
             foreach (NodePackage x in depTree) {
@@ -132,9 +162,14 @@ private NodePackage ExtractDependencyInfo(JsonProperty dependency) {
                     resulstList.Add(temp);
                 }
             }
-            return resulstList ?? [];
+            return resulstList;
         }
 
+        /// <summary>
+        /// Searches for all node package dependencies of a single node package.
+        /// </summary>
+        /// <param name="nodePackage">Node package to search</param>
+        /// <returns>List of all node package dependencies of a single node package.</returns>
         private List<NodePackage> analyzeSubtree(NodePackage nodePackage) {
             List<NodePackage> res = [];
             foreach(NodePackage x in nodePackage.Dependencies) {
@@ -144,6 +179,12 @@ private List<NodePackage> analyzeSubtree(NodePackage nodePackage) {
             return res;
         }
 
+        /// <summary>
+        /// Compares node package dependencies with cve data.
+        /// </summary>
+        /// <param name="package">Package to search for cve tracked dependencies.</param>
+        /// <param name="cveData">List of CveResult data.</param>
+        /// <returns>NodePackageResult with all dependencies and status if it is a cve tracked dependency.</returns>
         private NodePackageResult? checkVulnerabilities(NodePackage package, List<CveResult> cveData) {
             NodePackageResult r = new NodePackageResult() {
                 Name = "",
@@ -168,6 +209,11 @@ private List<NodePackage> analyzeSubtree(NodePackage nodePackage) {
             return r;
         }
 
+        /// <summary>
+        /// If Package is cve tracked, return true. Check all dependencies recursively.
+        /// </summary>
+        /// <param name="package"></param>
+        /// <returns>True if any dependency is tracked. False if no dependencies are tracked.</returns>
         private bool depCheck(NodePackageResult package) {
             foreach (NodePackageResult x in package.Dependencies) {
                 bool isTracked = depCheck(x);