{"id":18417951,"url":"https://github.com/quark-engine/quark-script","last_synced_at":"2025-09-07T07:41:24.712Z","repository":{"id":64381003,"uuid":"564198278","full_name":"quark-engine/quark-script","owner":"quark-engine","description":"Collections of Quark Script that detect vulnerabilities in the binaries.","archived":false,"fork":false,"pushed_at":"2025-01-22T11:09:35.000Z","size":1513,"stargazers_count":17,"open_issues_count":2,"forks_count":14,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-07T12:48:36.841Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quark-engine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-10T07:48:26.000Z","updated_at":"2025-01-22T11:09:39.000Z","dependencies_parsed_at":"2023-02-17T03:15:52.661Z","dependency_job_id":"5120ffb2-8e51-41cd-a78a-69cc5085b5c6","html_url":"https://github.com/quark-engine/quark-script","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/quark-engine/quark-script","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quark-engine%2Fquark-script","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quark-engine%2Fquark-script/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quark-engine%2Fquark-script/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quark-engine%2Fquark-script/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quark-engine","download_url":"https://codeload.github.com/quark-engine/quark-script/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quark-engine%2Fquark-script/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264283834,"owners_count":23584617,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T04:12:22.226Z","updated_at":"2025-07-08T14:04:39.698Z","avatar_url":"https://github.com/quark-engine.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Quark Script Agent\n\nIntroducing Quark's new member, the Quark Script Agent, the first AI assistant in the Quark team. This agent enables users to perform analyses using natural language, without the need for programming or scripting expertise, making the process simple and user-friendly.\n\nThe Quark Script Agent integrates with LangChain, which utilizes OpenAI's large language models to act as a bridge between natural language and the Quark Script API. LangChain defines the Quark Script API as a tool that large language models can understand and use. This means that users can easily call new analysis APIs using natural language commands by simply adding new tools as needed.\n\n## Showcase: Detecting CWE-798 with Quark Script Agent\nHere's an example of using the Quark Script Agent with the `quarkScriptAgent.py`. This agent can currently detect [CWE-798](https://cwe.mitre.org/data/definitions/798.html) vulnerability in the [ovaa.apk](https://github.com/oversecured/ovaa). See the details below.\n\n### Quick Start\n\n1. clone the repository:\n```\ngit clone https://github.com/quark-engine/quark-script.git\n```\n\n2. Install the required packages:\n```\npip install -r requirements.txt\n```\n\n3. Add your OpenAI API key in quarkscriptAgent.py.\n```python\nos.environ[\"OPENAI_API_KEY\"] = {your API Key}\n```\n\n4. Run the script:\n```\npython quarkScriptAgent.py\n```\n\n5. Result:\n\n\u003cimg width=\"1440\" alt=\"截圖 2024-07-26 下午3 39 12\" src=\"https://hackmd.io/_uploads/SJZZpf9FR.png\"\u003e\n\n### Decode the Prompts\nHere are two prompts, each for executing different analysis processes.\n\n```\n1st Prompt: Initialize the rule instance with the rule path set to \"constructCryptoGraphicKey.json\"\n```\nUsed Quark Script APIs/Tools that LLM used:  `loadRule`\n\n```\n2nd Prompt: Run Quark Analysis using the rule instance on the apk sample \"ovaa.apk\", \n            and Check if the parameters are hard-coded. If yes, display the hard-coded values.\n```\nUsed Quark Script APIs/Tools that LLM used: `runQuarkAnalysis`, `getBehaviorOccurList`, `getParameterValues` and `isHardCoded`\n\nThe `loadRule`, `runQuarkAnalysis`, `getBehaviorOccurList`, `getParameterValues`, and `isHardCoded` functions are treated as **tools** within LangChain, enabling them to be invoked through the `gpt-4o` model to analyze and identify [CWE-798](https://cwe.mitre.org/data/definitions/798.html) vulnerabilities in the [ovaa.apk](https://github.com/oversecured/ovaa) sample.\n\n\u003cimg width=\"845\" alt=\"截圖 2024-07-27 下午8 45 25\" src=\"https://hackmd.io/_uploads/BkplMjvYR.png\"\u003e\n\n\n## Showcase: Generating Quark Script with Quark Script Agent\n\nQuark Script Agent allows you to automate the creation of Quark Script code. This lets users concentrate on designing the detection process, while the LLM and Quark Script API handle the coding. This approach greatly enhances efficiency and streamlines the workflow.\n\nHere's an example for generating a Quark Script to detect CWE-798.\n\n### Demo Video\n\nhttps://github.com/user-attachments/assets/dc0e782b-3500-4260-a961-c499c14e495c\n\n### Decode the Prompts\n\nNow, let's instruct the Quark Script Agent to detect CWE-798 and write the Quark Script for the detection process using the following prompt.\n\n#### Assign a role to the Agent\n\nTo make the Quark Script Agent's responses more precise and relevant to vulnerability detection, we assign it the role of an Android APK vulnerability analyst.\n\n```!\nUser: \nNow you are an Android APK vulnerability analyst. Please follow the steps below to analyze a sample.\n```\n\n```!\nAgent: \nSure, I'd be happy to help with that. Please provide the sample APK file and the detection rule file that you would like to use for the analysis.\n```\n\n#### Instruct the detection process\n\nInstruct the Quark Script Agent to detect CWE-798 using the following detection process.\n\n```!\nDetection Process:\n1. Define the behavior \"Construct Cryptographic Key\" in the rule instance.\n2. Run Quark Analysis using the rule instance on the APK sample.\n3. Obtain all instances of detected behaviors from the Quark Analysis results.\n4. Retrieve the parameter values for each occurred behavior.\n5. Check if any parameters are hard-coded. If found, print the hard-coded parameters.\n```\n\n\u003eNote: The prompt will include details like the sample or rule path.\n\n\n1. Define the behavior \"Construct Cryptographic Key\" in the rule instance.\n```!\nUser: \n1. Define the behavior \"Construct Cryptographic Key\" in the rule instance, with the rule path set to \"constructCryptoGraphicKey.json\".\n```\n\n```!\nAgent: \nThe behavior \"Construct Cryptographic Key\" has been successfully defined in the rule instance with the rule path set to \"constructCryptoGraphicKey.json\". How would you like to proceed?\n```\n\n2. Run Quark Analysis using the rule instance on the APK sample.\n```!\nUser:\n2. Run Quark Analysis using the rule instance on the APK sample \"ovaa.apk\".\n```\n```!\nAgent:\nThe Quark analysis on the APK sample \"ovaa.apk\" has been completed successfully. What would you like to do next?\n```\n\n3. Obtain all instances of detected behaviors from the Quark Analysis results.\n```!\nUser:\n3. Obtain all instances of detected behaviors from the Quark Analysis results in the sample \"ovaa.apk\".\n```\n\n```!\nAgent\nI have obtained all instances of detected behaviors from the Quark Analysis results in the sample \"ovaa.apk\". If you need further details or specific information about these behaviors, please let me know!\n```\n\n4. Retrieve the parameter values for each occurred behavior.\n```!\nUser:\n4. Retrieve the parameter values for each occurred behavior.\n```\n\n```!\nAgent:\nThe parameter values for the occurred behavior are:\n1. \"49u5gh249gh24985ghf429gh4ch8f23f\"\n2. \"AES\"\n\nWould you like to check if any of these values are hard-coded?\n```\n\n5. Check if any parameters are hard-coded. If found, print the hard-coded parameters.\n```!\nUser:\n5. Check if any parameter values are hard-coded. If yes, display the hard-coded values.\n```\n\n```!\nAgent:\nThe following parameter values are hard-coded:\n\n1. `49u5gh249gh24985ghf429gh4ch8f23f`\n2. `AES`\n```\n\n#### Generate Quark Script\nFinally, ask the Quark Script Agent to write and execute the Python code based on the detection process outlined above.\n\n```!\nUser:\nUsing the Quark Script API, implement the above logic in Python and save it to 'detectCWE798.py', with the rule path set to 'constructCryptoGraphicKey.json' and the sample path to 'ovaa.apk'.\n```\n\n```!\nAgent:\nThe code has been written to `detectCWE798.py`. You can now execute this script to perform the analysis.\n```\n\nHere is the generated code:\n```python\nfrom quark.script import Rule, runQuarkAnalysis\n\n# Load the rule\nrule_path = 'constructCryptoGraphicKey.json'\nrule_instance = Rule(rule_path)\n\n# Define the sample path\nsample_path = 'ovaa.apk'\n\n# Run the Quark analysis\nquark_result = runQuarkAnalysis(sample_path, rule_instance)\n\n# Extract the behavior occurrence list\nbehavior_occur_list = quark_result.behaviorOccurList\n\n# Iterate through each behavior and get parameter values\nfor behavior in behavior_occur_list:\n    param_values = behavior.getParamValues()\n    for param in param_values:\n        # Check if the parameter value is hardcoded\n        is_hardcoded = quark_result.isHardcoded(param)\n        if is_hardcoded:\n            print(f'Hardcoded value found: {param}')\n```\n\n```!\nUser:\nExecute detectCWE798.py\n```\n\nHere is the result.\n```shell\nHardcoded value found: 49u5gh249gh24985ghf429gh4ch8f23f\nHardcoded value found: AES\n```\n\nWe added 2 tools, `writeCodeInFile` and `executeCode`, to enable Quark Script Agent to generate and execute Quark Script code.\n\n### \n\u003cimg width=\"845\" alt=\"截圖 2024-07-27 下午8 45 25\" src=\"https://github.com/user-attachments/assets/d8fd805a-86c9-4eff-b120-d340fc43d792\"\u003e\n\n\n* Notes: \n  1. The code is generated by OpenAI's GPT model, and the output may not always match the documentation exactly.\n  2. Since LangChain currently does not support passing Python instances between tools, we are temporarily using global variables to pass parameters between tools in `quarkScriptAgent.py`.\n  3. Place the rules, samples, and `quarkScriptAgent.py` in the same folder; the LLM will automatically find files with matching names.\n  4. A web GUI is under construction, please stay tuned!\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquark-engine%2Fquark-script","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquark-engine%2Fquark-script","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquark-engine%2Fquark-script/lists"}