Merge pull request #144 from Washi1337/cicd

Update CI/CD pipeline

.github/workflows/linux.yml

@@ -7,26 +7,69 @@ on:
     branches: [ master ]
 
 jobs:
-  build:
+  get-version:
+    name: Calculating Version Suffix
+    runs-on: ubuntu-22.04
+    outputs:
+      version_suffix: ${{ steps.set-vars.outputs.version_suffix }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - id: git-vars
+        name: Get git branch information
+        shell: bash
+        run: |
+          echo "##[set-output name=git_branch;]$(echo $GITHUB_REF)"
+          echo "::set-output name=git_hash::$(git rev-parse --short HEAD)"
 
-    runs-on: ubuntu-latest
+      - id: set-vars
+        uses: actions/github-script@v7
+        with:
+          script: |
+            let runNumber = "${{ github.run_number }}";
+            let gitHash = "${{ steps.git-vars.outputs.git_hash }}";
+            let rawGitRef = "${{ steps.git-vars.outputs.git_branch }}";
+            console.log("rawGitRef: " + rawGitRef);
+            let gitRef = rawGitRef.replace(/^refs\/heads\//, "").replace(/^refs\/heads\//, "").replace(/[_//!@#$%&]/g, "-");
+            if(gitRef.indexOf("refs/pull/") === 0) {
+              gitRef = "pr-" + gitRef.substring(10, gitRef.lastIndexOf("/"));
+            }
+            var versSuffix = `${gitRef}.${runNumber}+${gitHash}`;
+            console.log("Final computed version suffix: " + versSuffix);
+            core.setOutput("version_suffix", versSuffix);
 
+  build:
+    name: Build and Test
+    runs-on: ubuntu-22.04
+    needs: [get-version]
     steps:
-    - name: Checkout
-      uses: actions/checkout@v3
-      with:
-        submodules: recursive
-
-    - name: Setup .NET SDK
-      uses: actions/setup-dotnet@v3
-      with:
-        dotnet-version: 8.0.100
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          submodules: recursive
 
-    - name: Install dependencies
-      run: dotnet restore
-
-    - name: Build
-      run: dotnet build --configuration Release --no-restore
-
-    - name: Test
-      run: dotnet test --no-restore --verbosity minimal
+      - name: Setup .NET Sdk
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: | 
+            6.0.x
+            8.0.x
+         
+      - name: Get Installed .NET Information
+        run: dotnet --info
+
+      - name: Install dependencies
+        run: dotnet restore --property:VersionSuffix=${{needs.get-version.outputs.version_suffix}}
+
+      - name: Build
+        run: dotnet build --configuration Release --no-restore --property:VersionSuffix=${{needs.get-version.outputs.version_suffix}}
+
+      - name: Test
+        run: dotnet test --no-restore --verbosity minimal
+
+      - name: Push to NuGet Nightly
+        env: 
+          NIGHTLY_NUGET_SOURCE: ${{ secrets.NIGHTLY_NUGET_SOURCE }}
+          NIGHTLY_NUGET_API_KEY: ${{ secrets.NIGHTLY_NUGET_API_KEY }}
+        if: ${{github.ref == 'refs/heads/master' && env.NIGHTLY_NUGET_SOURCE != '' && env.NIGHTLY_NUGET_API_KEY != '' }}
+        run: dotnet nuget push "./artifacts/**/*.nupkg" -k ${{env.NIGHTLY_NUGET_API_KEY}} -s ${{env.NIGHTLY_NUGET_SOURCE}} --skip-duplicate

.gitignore

@@ -14,3 +14,4 @@ Thumbs.db
 Desktop.ini
 .DS_Store
 
+artifacts/

Directory.Build.props

@@ -1,13 +1,20 @@
 <Project>
 
     <PropertyGroup>
-        <Copyright>Copyright © Washi 2019-2023</Copyright>
+        <Copyright>Copyright © Washi 2019-2025</Copyright>
         <PackageProjectUrl>https://github.com/Washi1337/Echo</PackageProjectUrl>
         <PackageLicense>https://github.com/Washi1337/Echo/LICENSE.md</PackageLicense>
         <RepositoryUrl>https://github.com/Washi1337/Echo</RepositoryUrl>
         <RepositoryType>git</RepositoryType>
-        <LangVersion>10</LangVersion>
-        <Version>0.9.0.1</Version>
+        <LangVersion>12</LangVersion>
+        <Nullable>enable</Nullable>
+        <VersionPrefix>1.0.0</VersionPrefix>
+        <VersionSuffix>alpha.1</VersionSuffix>
+        <Deterministic>true</Deterministic>
+        <UseArtifactsOutput>true</UseArtifactsOutput>
     </PropertyGroup>
 
+    <PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
+        <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
+    </PropertyGroup>
 </Project>

Echo.sln

@@ -7,6 +7,9 @@ EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Echo.DataFlow", "src\Core\Echo.DataFlow\Echo.DataFlow.csproj", "{2D940041-E424-4960-AF1D-A0ECA48DB7F4}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{620B6332-1C8B-4C82-BE28-5D62765C96F0}"
+	ProjectSection(SolutionItems) = preProject
+		test\Directory.Build.props = test\Directory.Build.props
+	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Core", "Core", "{91D56580-50E2-49B4-A5C0-DB83C9AADF8D}"
 EndProject
@@ -23,6 +26,9 @@ EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Echo.ControlFlow.Tests", "test\Core\Echo.ControlFlow.Tests\Echo.ControlFlow.Tests.csproj", "{F52C85BF-C329-4DF7-A8D8-E9A7E1925D1C}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{7B5309CC-0188-475C-9449-074CAA925A4B}"
+	ProjectSection(SolutionItems) = preProject
+		src\Directory.Build.props = src\Directory.Build.props
+	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "deps", "deps", "{F3162144-2D6C-4FD9-B8BB-DCCD49C87989}"
 EndProject
@@ -49,6 +55,7 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{83706566-D2F1-463F-B8B7-E8D870709657}"
 	ProjectSection(SolutionItems) = preProject
 		Directory.Build.props = Directory.Build.props
+		.gitignore = .gitignore
 	EndProjectSection
 EndProject
 Global

README.md

@@ -1,59 +1,72 @@
-Echo
-====
+# Echo
 
-Echo is an experimental generic, static analysis, symbolic execution and emulation framework, that aims to help out with binary code analysis for a variety of platforms.
+Echo is an experimental generic, static analysis, symbolic execution and emulation framework, that aims to help out with binary code analysis for a variety of platforms or backends.
 
 Echo is released under the LGPLv3 license.
 
-Main Features
--------------
-- Control flow analysis
-    - Create static and symbolic flow graphs
-    - Dominator analysis
-    - Serialize into scoped flow blocks or a list of instructions
-- Data flow analysis
-    - Create data flow graphs
-    - Inspect stack and variable dependencies of instructions.
-- AST building
-    - Lift control flow graphs to Abstract Syntax Trees (ASTs).
-- Unified generic API.
-    - Serialize any kind of graph to the dot file format.
-    - Adding a new platform for flow analysis requires minimal effort
 
+## Main Features
 
-Supported platforms:
+- [x] Generic Graph Models
+  - [x] Traversal and structural detection algorithms
+  - [x] Serialization to Dot/GraphViz
+- [x] Generic Control flow Analysis
+    - [x] Create static and symbolic flow graphs
+    - [x] Dominator analysis
+    - [x] Serialize into scoped flow blocks or a list of instructions
+- [x] Generic Data flow Analysis
+    - [x] Create data flow graphs
+    - [x] Inspect stack and variable dependencies of instructions
+- [x] Generic AST Construction
+    - [x] Lift control flow graphs to Abstract Syntax Trees (ASTs)
+    - [x] Automatic variable cross-referencing
+- [x] Generic Emulation Engine Framework
+  - [x] Virtual memory model using low level bit vectors
+  - [x] Support for HLE and LLE arithmetic on fully known, partially known and fully unknown bit vectors of any size
 
-| Architecture | Back-end                                                | Control Flow | Data Flow | AST | Purity Classification | Emulation |
-|--------------|---------------------------------------------------------|--------------|-----------|-----|-----------------------|-----------|
-| CIL          | [AsmResolver](https://github.com/Washi1337/AsmResolver) | ✓            | ✓         | ✓   | ✓                     | ✓ (WIP)   |
-| CIL          | [dnlib](https://github.com/0xd4d/dnlib)                 | ✓            | ✓         | ✓   | ✓                     |           |
-| x86 (32-bit) | [Iced](https://github.com/icedland/iced)                | ✓            | ✓         | ✓   |                       |           |
-| x86 (64-bit) | [Iced](https://github.com/icedland/iced)                | ✓            | ✓         | ✓   |                       |           |
 
+## Supported Backends:
 
-Compiling
----------
+| Architecture | Back-end                                                | Control Flow | Data Flow | AST     | Purity Classification | Emulation |
+|--------------|---------------------------------------------------------|--------------|-----------|---------|-----------------------|-----------|
+| CIL          | [AsmResolver](https://github.com/Washi1337/AsmResolver) | ✓            | ✓         | ✓       | ✓                     | ✓ (WIP)   |
+| CIL          | [dnlib](https://github.com/0xd4d/dnlib)                 | ✓            | ✓         | ✓       | ✓                     |           |
+| x86 (32-bit) | [Iced](https://github.com/icedland/iced)                | ✓            | ✓         | ✓ (WIP) |                       |           |
+| x86 (64-bit) | [Iced](https://github.com/icedland/iced)                | ✓            | ✓         | ✓ (WIP) |                       |           |
 
-Echo can be built using `dotnet build`, or any IDE that is capable of building .NET Standard 2.0 projects (such as Visual Studio or JetBrains Rider).
-
-Not all projects need to be built for a working binary to be produced. Only the core libraries found in `src/Core` are required to be built. Any other project, such as the platform-specific back-ends in the `src/Platforms` directory and the test projects in `test/`, is optional and can be unloaded safely.
 
+## Binaries
 
-Build Status
-------------
+- [Nightly NuGet Feed](https://nuget.washi.dev/)
 
 | Branch | Status (Linux)                                                                  |
 |--------|---------------------------------------------------------------------------------|
 | master | ![Linux](https://github.com/Washi1337/Echo/workflows/Linux/badge.svg)           |
 
-Documentation
--------------
+
+## Compiling
+
+Simply run 
+
+```
+dotnet build
+```
+
+Alternatively, use any IDE that is capable of building .NET Standard 2.0 projects (such as Visual Studio or JetBrains Rider).
+
+Not all projects need to be built for a working binary to be produced. Only the core libraries found in `src/Core` are required to be built. Any other project, such as the platform-specific back-ends in the `src/Platforms` directory and the test projects in `test/`, is optional and can be unloaded safely.
+
+
+## Documentation
+
 Check out the [wiki](https://echo-emu.readthedocs.io/) for guides and information on how to use the library!
 
-Contributing
-------------
+
+## Contributing
+
 See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-Found a bug or have questions?
-------------------------------
+
+## Found a bug or have questions?
+
 Please use the [issue tracker](https://github.com/Washi1337/Echo/issues). Try to be as descriptive as possible.

src/Core/Echo.Ast/Echo.Ast.csproj

@@ -1,12 +1,9 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
     <PropertyGroup>
-        <TargetFramework>netstandard2.0</TargetFramework>
         <Title>Echo.Ast</Title>
         <Description>Abstract Syntax Tree (AST) builders for the Echo program analysis toolsuite.</Description>
         <PackageTags>program code analysis ast lifting</PackageTags>
-        <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
-        <Nullable>enable</Nullable>
     </PropertyGroup>
 
     <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">

src/Core/Echo.Ast/Patterns/ExpressionStatementPattern.cs

@@ -59,6 +59,6 @@ public ExpressionStatementPattern<TInstruction> WithExpression(Pattern<Expressio
         }
 
         /// <inheritdoc />
-        public override string ToString() => Expression.ToString();
+        public override string ToString() => Expression.ToString()!;
     }
 }

src/Core/Echo.Ast/Patterns/VariableExpressionPattern.cs

@@ -49,7 +49,7 @@ protected override void MatchChildren(Expression<TInstruction> input, MatchResul
         }
 
         /// <inheritdoc />
-        public override string ToString() => Variable.ToString();
+        public override string ToString() => Variable.ToString()!;
 
         /// <summary>
         /// Captures the embedded variable.

src/Core/Echo.ControlFlow/Analysis/Domination/DominatorTreeNodeAdorner.cs

@@ -5,19 +5,32 @@
 
 namespace Echo.ControlFlow.Analysis.Domination;
 
+/// <summary>
+/// Implements an adorner that styles a tree node in a dominator tree as a normal control flow node.
+/// </summary>
+/// <typeparam name="TInstruction">The type of instructions stored in the node.</typeparam>
 public class DominatorTreeNodeAdorner<TInstruction> : IDotNodeAdorner 
     where TInstruction : notnull
 {
+    /// <summary>
+    /// Creates an adorner with the default control flow node adorner.
+    /// </summary>
     public DominatorTreeNodeAdorner()
         : this(new ControlFlowNodeAdorner<TInstruction>())
     {
     }
 
+    /// <summary>
+    /// Creates an adorner with the specified underlying control flow node adorner.
+    /// </summary>
     public DominatorTreeNodeAdorner(IDotNodeAdorner nodeAdorner)
     {
         NodeAdorner = nodeAdorner;
     }
 
+    /// <summary>
+    /// Gets or sets the underlying control flow node adorner.
+    /// </summary>
     public IDotNodeAdorner NodeAdorner { get; set; }
 
     /// <inheritdoc />

src/Core/Echo.ControlFlow/Echo.ControlFlow.csproj

@@ -1,14 +1,9 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
     <PropertyGroup>
-        <TargetFramework>netstandard2.0</TargetFramework>
         <Title>Echo.ControlFlow</Title>
         <Description>Control flow models and algorithms for the Echo program analysis toolsuite.</Description>
         <PackageTags>program code analysis control-flow-graph blocks serialization dominator-analysis</PackageTags>
-        <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
-        <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
-        <Nullable>enable</Nullable>
-        <LangVersion>12</LangVersion>
     </PropertyGroup>
 
     <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">

src/Core/Echo.ControlFlow/Serialization/Dot/DefaultInstructionFormatter.cs

@@ -16,6 +16,6 @@ public static DefaultInstructionFormatter<TInstruction> Instance
         } = new();
 
         /// <inheritdoc />
-        public string Format(in TInstruction instruction) => instruction.ToString();
+        public string Format(in TInstruction instruction) => instruction.ToString()!;
     }
 }

src/Core/Echo.DataFlow/Collections/VariableDependencyCollection.cs

@@ -2,6 +2,7 @@
 using System.Collections;
 using System.Collections.Generic;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 using System.Linq;
 using Echo.Code;
 
@@ -73,8 +74,10 @@ private void AssertDependencyValidity(VariableDependency<TInstruction> item)
         /// <param name="variable">The variable.</param>
         /// <param name="dependency">When this function returns <c>true</c>, contains the dependency.</param>
         /// <returns><c>true</c> if the variable was registered as a dependency, <c>false</c> otherwise.</returns>
-        public bool TryGetDependency(IVariable variable, out VariableDependency<TInstruction> dependency) => 
-            _entries.TryGetValue(variable, out dependency);
+        public bool TryGetDependency(IVariable variable, [NotNullWhen(true)] out VariableDependency<TInstruction>? dependency)
+        {
+            return _entries.TryGetValue(variable, out dependency);
+        }
 
         /// <summary>
         /// Adds a variable dependency to the node.

src/Core/Echo.DataFlow/Construction/StateTransitioner.cs

@@ -42,6 +42,9 @@ public DataFlowGraph<TInstruction> DataFlowGraph
             get;
         }
 
+        /// <summary>
+        /// Gets a mapping between offsets to data flow nodes. 
+        /// </summary>
         public IDictionary<long, DataFlowNode<TInstruction>> OffsetMap
         {
             get;

src/Core/Echo.DataFlow/Echo.DataFlow.csproj

@@ -1,13 +1,9 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
     <PropertyGroup>
-        <TargetFramework>netstandard2.0</TargetFramework>
         <Title>Echo.DataFlow</Title>
         <Description>Data flow models and algorithms for the Echo program analysis toolsuite.</Description>
         <PackageTags>program code analysis data-flow-graph slicing dependency-analysis</PackageTags>
-        <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
-        <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
-        <Nullable>enable</Nullable>
     </PropertyGroup>
 
     <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
@@ -25,6 +21,7 @@
 
     <ItemGroup>
       <PackageReference Include="System.Collections.Immutable" Version="1.7.1" />
+      <PackageReference Include="Nullable" Version="1.3.1" />
     </ItemGroup>
 
 </Project>