diff --git a/solidity/codeql/README.md b/solidity/codeql/README.md
new file mode 100644
index 0000000..fc52dae
--- /dev/null
+++ b/solidity/codeql/README.md
@@ -0,0 +1,91 @@
+---
+slug: /
+---
+
+
+# CyScout
+
+## Run queries and detect vulnerabilities in your smart contracts using CodeQL-Solidity
+
+)
+
+This repository contains CoinFabrik's ongoing research and development to extend CodeQL support to the Solidity smart contract language. By leveraging the foundational work done by the CodeQL team for Ruby, we have adapted and expanded their approach to create a powerful toolset for analyzing Solidity code.
+
+## 🔍 Overview
+
+Our goal is to provide a comprehensive set of tools for querying and detecting vulnerabilities in Solidity smart contracts. We build upon the work of [Joran Honig's Solidity Tree-sitter grammar](https://github.com/JoranHonig/tree-sitter-solidity) and the CodeQL team's [Ruby implementation](https://github.blog/security/web-application-security/code-scanning-and-ruby-turning-source-code-into-a-queryable-database/). The project includes an extractor, database schema generation, and abstractions such as a cleaner Abstract Syntax Tree (AST), Control Flow Graph (CFG), and Dataflow analysis. These elements enable complex vulnerability detection and querying, similar to the C++ libraries in CodeQL.
+
+## 🚀 Project Status
+
+- **Extractor and Database Schema**: Usable and functional for Solidity codebases.
+- **Current Work**: We are actively developing a cleaner AST, CFG, and Dataflow support to enhance the detection of vulnerabilities.
+- **Proof of Concept (PoC)**: Nine simple detector examples are provided to demonstrate basic usage and potential.
+
+## 🏁 Getting Started
+
+To get started with analyzing Solidity smart contracts using CodeQL, follow these steps:
+
+### Setting Up CodeQL Solidity
+
+Work in progress
+
+### Install CodeQL Solidity Extension
+
+
+### Run Sample Detectors
+
+Once the database is created, you can run sample detectors written in the QL language:
+
+```bash
+codeql query run /path-to-detector/ -d /path-to-created-database/
+```
+
+For instance:
+
+```shell
+[1/1] Found in cache: /home/user/codeql/solidity/ql/lib/detector3.ql.
+detector3.ql: Evaluation completed (191ms).
+| col0 | col1 |
++-----------------+------------------------------------------------------------------------------+
+| YulFunctionCall | /home/user/codeql/solidity-test/bitshift-order-test/vulnerable.sol@4:18:4:26 |
+Shutting down query evaluator.
+```
+
+## Detectors
+
+| Num | Detector | What it Detects |
+| --- | ----------- | -------------------------------------------------------------------- |
+| 1 | `transfer-from` | transferFrom uses arbitrary `from` |
+| 2 | `incorrect-shift` | incorrect order of arguments in bit shift operations |
+| 3 | `msg-valu-in-for-loop` | Detects the use of msg.value inside a loop |
+| 4 | `bad-prng` | Detects bad randomness |
+| 5 | `divide-before-multiply` | Detects loss of precision |
+| 6 | `incorrect-exp` | Detects use of bitwise xor instead of exponential |
+| 7 | `unchecked-send` | The return value of a send is not checked |
+| 8 | `is-unreachable` | Detects dead code |
+| 9 | `unprotected-self-destruct` | Detects unprotected call to selfdestruct/suicidal |
+
+
+### Further Documentation
+
+## Work In Progress
+
+We are actively working on enhancing the capabilities of our Solidity CodeQL implementation. Our current focus and status is on:
+
+- AST: usable
+- CFG: experimental
+- DFA: soon
+
+For more detailed instructions on using CodeQL, refer to the [official CodeQL documentation](https://codeql.github.com/docs/).
+
+## 🤝 Contributing
+
+We welcome contributions to enhance and expand the support for Solidity in CodeQL. Feel free to submit issues, feature requests, or pull requests.
+
+For more information, please refer to the [Contribution Guidelines](/docs/Contributing.md).
+
+## License
+
+The code in this repository is licensed under the [MIT License](LICENSE.md) by CoinFabrik.
+
+For further information on CodeQL and CodeQL CLI licensing, please refer to the official [repo](https://github.com/github/codeql-cli-binaries).
diff --git a/solidity/codeql/docs/docs/Classes/index.md b/solidity/codeql/docs/docs/Classes/index.md
index 28fbdb0..df2ec38 100644
--- a/solidity/codeql/docs/docs/Classes/index.md
+++ b/solidity/codeql/docs/docs/Classes/index.md
@@ -5,12 +5,12 @@ title: Classes
# Classes Index
-- Access
-- BasicBlock
-- Block
-- Call
-- ControlFlowGraph
-- Enclosing
-- Function
-- Specifier
-- SubBasicBlock
\ No newline at end of file
+- [Access](../Classes/Access.md)
+- [BasicBlock](../Classes/BasicBlock.md)
+- [Block](../Classes/Block.md)
+- [Call](../Classes/Call.md)
+- [ControlFlowGraph](../Classes/ControlFlowGraph.md)
+- [Enclosing](../Classes/Enclosing.md)
+- [Function](../Classes/Function.md)
+- [Specifier](../Classes/Specifier.md)
+- [SubBasicBlock](../Classes/SubBasicBlock.md)
\ No newline at end of file
diff --git a/solidity/codeql/docs/docs/Contributing.md b/solidity/codeql/docs/docs/Contributing.md
new file mode 100644
index 0000000..bcdf97b
--- /dev/null
+++ b/solidity/codeql/docs/docs/Contributing.md
@@ -0,0 +1,29 @@
+# Contribute
+
+Thank you for your interest in contributing to the development of new detectors.
+
+### Getting Started
+
+Create a new issue on our [repository](https://github.com/CoinFabrik/CyScout) with the name of the new detector or test case you wish to contribute. Then, link a new branch to that issue.
+
+### Detectors
+
+In order to build a custom detector, you need to first import all static analysis primitives you need to use.
+
+- `import codeql.solidity.ast.AST` for AST language constructs (binary, unary and tertiary operations, control statements, loops, functions, contracts, etc.)
+
+- `import codeql.solidity.controlflow.ControlFlowGraph` for CFG constructs (SSA, basic blocks, control flow nodes, etc.)
+
+- `import codeql.solidity.dataflow.DataFlow` for DFA constructs (to define sinks and sources for local flow analysis)
+
+For global data flow analysis, you must write a class that implements DataFlow::ConfigSig. Refer to our global flow example or to the official codeQL guide for more information on this specific case.
+
+### Test Cases
+
+When you create a new detector, please also add a new test case. To add a new one:
+
+1. Create a new folder in the [`tests`](https://github.com/CoinFabrik/stacy/tree/main/tests) directory. **Remember to follow the snake_case/underscore naming convention for the folder name**.
+
+2. Within this folder, create two directories: `vulnerable-example` and `remediated-example`. Fill each with the relevant files for their respective test cases.
+
+For guidance, refer to the `detector_name` template in [`templates/test-case`](https://github.com/CoinFabrik/stacy/tree/main/templates/tests).
\ No newline at end of file
diff --git a/solidity/codeql/docs/docs/readme.md b/solidity/codeql/docs/docs/readme.md
index b082bb8..335683b 100644
--- a/solidity/codeql/docs/docs/readme.md
+++ b/solidity/codeql/docs/docs/readme.md
@@ -19,76 +19,20 @@ Our goal is to provide a comprehensive set of tools for querying and detecting v
- **Extractor and Database Schema**: Usable and functional for Solidity codebases.
- **Current Work**: We are actively developing a cleaner AST, CFG, and Dataflow support to enhance the detection of vulnerabilities.
-- **Proof of Concept (PoC)**: Three simple detector examples are provided to demonstrate basic usage and potential.
+- **Proof of Concept (PoC)**: Nine simple detector examples are provided to demonstrate basic usage and potential.
## 🏁 Getting Started
To get started with analyzing Solidity smart contracts using CodeQL, follow these steps:
-### 1️⃣ Install CodeQL CLI
+### Setting Up CodeQL Solidity
-First, download and install the CodeQL CLI by following the instructions provided in the [official CodeQL CLI repository](https://github.com/github/codeql-cli-binaries).
+Work in progress
-### Clone CodeQL repository
+### Install CodeQL Solidity Extension
-Clone this repository from [CodeQl](https://github.com/github/codeql)
-### 2️⃣ Setting up Solidity Extractor
-
-- Go to `cyscout/solidity/codeql/extractor-pack/tools` and give all `.sh` files execute permissions. This is:
-
-```bash
-chmod +x *.sh
-```
-
-- Copy the `solidity` and `solidity-test` folders of this repository (`cyscout`) inside `CodeQL CLI repository` and `CodeQL`. Both at root level.
-
-- Inside `CodeQL` repository, in this path `codeql/solidity` run:
-
-```shell
-bash scripts/create-extractor-pack.sh
-```
-
-You should see
-
- -->
-
-### 3️⃣ Extract Solidity Code
-
-To create a CodeQL database from a Solidity codebase, run the following command:
-
-```shell
-codeql database create /path-to-database/ -l solidity -s /path-to-solidity-codebase/ --search-path /path-to-[solidity/extractor-pack]/
-```
-
-If all went smoothly, you should see something of the kind:
-
-```shell
-
-codeql database create /home/user/codeql/solidity-test/test-db-bitshift-examples -l solidity -s /home/user/codeql/solidity-test/bitshift-order-test --search-path ../solidity/extractor-pack --overwrite
-Initializing database at /home/user/codeql/solidity-test/test-db-bitshift-examples.
-Running build command: []
-Running command in /home/user/codeql/solidity-test/bitshift-order-test: [/home/user/codeql/solidity/extractor-pack/tools/autobuild.sh]
-[2024-09-03 12:55:56] [build-stderr] Scanning for files in /home/user/codeql/solidity-test/bitshift-order-test...
-[2024-09-03 12:55:56] [build-stderr] /home/user/codeql/solidity-test/test-db-bitshift-examples: Indexing files in in /home/user/codeql/solidity-test/bitshift-order-test...
-[2024-09-03 12:55:56] [build-stderr] Running command in /home/user/codeql/solidity-test/bitshift-order-test: [/home/user/codeql/solidity/extractor-pack/tools/index-files.sh, /home/user/codeql/solidity-test/test-db-bitshift-examples/working/files-to-index13975833793457248559.list]
-[2024-09-03 12:55:56] [build-stdout] [2024-09-03 12:55:56] [build-stdout] INFO Extraction started
-[2024-09-03 12:55:56] [build-stdout] [2024-09-03 12:55:56] [build-stdout] INFO Using 7 threads
-[2024-09-03 12:55:56] [build-stdout] [2024-09-03 12:55:56] [build-stdout] INFO extracting: /home/user/codeql/solidity-test/bitshift-order-test/remediated.sol
-[2024-09-03 12:55:56] [build-stdout] [2024-09-03 12:55:56] [build-stdout] INFO extracting: /home/user/codeql/solidity-test/bitshift-order-test/vulnerable.sol
-[2024-09-03 12:55:56] [build-stdout] [2024-09-03 12:55:56] [build-stdout] INFO Extraction complete
-Finalizing database at /home/user/codeql/solidity-test/test-db-bitshift-examples.
-Running TRAP import for CodeQL database at /home/user/codeql/solidity-test/test-db-bitshift-examples...
-Importing TRAP files
-Merging relations
-Finished writing database (relations: 4.86 KiB; string pool: 2.05 MiB).
-TRAP import complete (983ms).
-Finished zipping source archive (643.00 B).
-Successfully created database at /home/user/codeql/solidity-test/test-db-bitshift-examples.
-
-```
-
-### 4️⃣ Run Sample Detectors
+### Run Sample Detectors
Once the database is created, you can run sample detectors written in the QL language:
@@ -124,12 +68,22 @@ Shutting down query evaluator.
### Further Documentation
+## Work In Progress
+
+We are actively working on enhancing the capabilities of our Solidity CodeQL implementation. Our current focus and status is on:
+
+- AST: usable
+- CFG: experimental
+- DFA: soon
+
For more detailed instructions on using CodeQL, refer to the [official CodeQL documentation](https://codeql.github.com/docs/).
## 🤝 Contributing
We welcome contributions to enhance and expand the support for Solidity in CodeQL. Feel free to submit issues, feature requests, or pull requests.
+For more information, please refer to the [Contribution Guidelines](../docs/Contributing.md).
+
## License
The code in this repository is licensed under the [MIT License](LICENSE.md) by CoinFabrik.
diff --git a/solidity/codeql/docs/docusaurus.config.js b/solidity/codeql/docs/docusaurus.config.js
index e099f0a..d4ba009 100644
--- a/solidity/codeql/docs/docusaurus.config.js
+++ b/solidity/codeql/docs/docusaurus.config.js
@@ -10,7 +10,7 @@ import { themes as prismThemes } from "prism-react-renderer";
const config = {
title: "CyScout",
tagline: "Coinfabrik reasearch on CodeQL",
- favicon: "img/favicon.ico",
+ favicon: "img/favicon.png",
url: "https://coinfabrik.github.io",
@@ -58,29 +58,13 @@ const config = {
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
- image: "img/docusaurus-social-card.jpg",
+ image: "img/CyScout-Social-Card.jpg",
navbar: {
- title: "CyScout",
logo: {
- alt: "My Site Logo",
- src: "img/logo.svg",
+ alt: "Logo",
+ src: "img/logo-dark.svg",
+ srcDark: "img/logo-light.svg",
},
- /* items: [
- {
- type: "docSidebar",
- sidebarId: "tutorialSidebar",
- to: "/Classes",
- label: "Classes",
- position: "left",
- },
- {
- type: "docSidebar",
- sidebarId: "tutorialSidebar",
- to: "/Detectors",
- label: "Detectors",
- position: "left",
- },
- ], */
},
footer: {
style: "dark",
diff --git a/solidity/codeql/docs/package.json b/solidity/codeql/docs/package.json
index e00ec63..3f596cf 100644
--- a/solidity/codeql/docs/package.json
+++ b/solidity/codeql/docs/package.json
@@ -1,5 +1,5 @@
{
- "name": "codeql-research",
+ "name": "cyscout",
"version": "0.0.0",
"private": true,
"scripts": {
diff --git a/solidity/codeql/docs/static/img/docusaurus.png b/solidity/codeql/docs/static/img/docusaurus.png
deleted file mode 100644
index f458149..0000000
Binary files a/solidity/codeql/docs/static/img/docusaurus.png and /dev/null differ
diff --git a/solidity/codeql/docs/static/img/favicon.ico b/solidity/codeql/docs/static/img/favicon.ico
new file mode 100644
index 0000000..fbe2050
Binary files /dev/null and b/solidity/codeql/docs/static/img/favicon.ico differ
diff --git a/solidity/codeql/docs/static/img/favicon.png b/solidity/codeql/docs/static/img/favicon.png
deleted file mode 100644
index c1dbee3..0000000
Binary files a/solidity/codeql/docs/static/img/favicon.png and /dev/null differ
diff --git a/solidity/codeql/docs/static/img/logo.svg b/solidity/codeql/docs/static/img/logo.svg
deleted file mode 100644
index 9db6d0d..0000000
--- a/solidity/codeql/docs/static/img/logo.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/solidity/codeql/docs/static/img/undraw_docusaurus_mountain.svg b/solidity/codeql/docs/static/img/undraw_docusaurus_mountain.svg
deleted file mode 100644
index af961c4..0000000
--- a/solidity/codeql/docs/static/img/undraw_docusaurus_mountain.svg
+++ /dev/null
@@ -1,171 +0,0 @@
-
diff --git a/solidity/codeql/docs/static/img/undraw_docusaurus_react.svg b/solidity/codeql/docs/static/img/undraw_docusaurus_react.svg
deleted file mode 100644
index 94b5cf0..0000000
--- a/solidity/codeql/docs/static/img/undraw_docusaurus_react.svg
+++ /dev/null
@@ -1,170 +0,0 @@
-
diff --git a/solidity/codeql/docs/static/img/undraw_docusaurus_tree.svg b/solidity/codeql/docs/static/img/undraw_docusaurus_tree.svg
deleted file mode 100644
index d9161d3..0000000
--- a/solidity/codeql/docs/static/img/undraw_docusaurus_tree.svg
+++ /dev/null
@@ -1,40 +0,0 @@
-