ev-flow/quark-engine/rule-gen

Generate Quark Rule

Use this skill when the user wants to create a Quark rule that detects a specific malicious behavior. The skill guides you through identifying the right API pair, formatting Dalvik descriptors correctly, and validating that the rule actually matches the target APK.

Step 0 — Verify Quark is installed

quark --version

If this fails, stop and tell the user: "Quark not found — run pip install quark-engine and try again."

Step 1 — Get behavior description

Ask the user to describe the behavior they want to detect in plain English. Example: "Send the device's GPS location via SMS to a remote number."

Step 2 — Get code reference (required before proceeding)

A decompiled code snippet is required to identify the correct class names, method names, and descriptors. Without it, any generated rule is a guess and the retry loop has no new information.

If the user provides a code snippet: proceed to Step 3.

If no snippet is available: extract relevant method listings from the APK:

# Native Android SDK APIs only, filtered by suspected package — use this first
quark -i native -a "<apk_path>" | grep "<suspected_package>"
 
# Only if -i native finds nothing: fall back to all methods (very large output)
quark -i all -a "<apk_path>" | grep "<suspected_package>"

Ask the user which package namespace to search for, or search for the most likely Android SDK classes for the described behavior (e.g., SmsManager, LocationManager, TelephonyManager).

Step 3 — Identify the API pair

From the code snippet, identify exactly two Android API calls that together characterize the behavior:

• Both calls must appear in the same execution context
• Together, they must describe the malicious intent (e.g., "get location" + "send SMS")
• Neither call alone is sufficient — the pair is what makes it malicious

Step 4 — Format Dalvik descriptors

Quark rules use Dalvik bytecode descriptor syntax. Getting this wrong causes the rule to silently return zero results.

Class names:

• Format: L + package path (with / separators) + ;
• Example: Landroid/telephony/SmsManager;

Method descriptors:

• Format: (param1param2...)ReturnType
• No spaces between parameters — the parser uses type boundaries
• Reference type params end with ;, primitive params are single chars
• Example (two reference params, void return): (Ljava/lang/String;Landroid/content/Context;)V
• Wrong (space breaks parsing): (Ljava/lang/String; Landroid/content/Context;)V

Primitive types:

Verified example rule (sendLocation_SMS.json):

{
  "crime": "Send Location via SMS",
  "permission": [
    "android.permission.SEND_SMS",
    "android.permission.ACCESS_COARSE_LOCATION",
    "android.permission.ACCESS_FINE_LOCATION"
  ],
  "api": [
    {
      "class": "Landroid/telephony/TelephonyManager;",
      "method": "getCellLocation",
      "descriptor": "()Landroid/telephony/CellLocation;"
    },
    {
      "class": "Landroid/telephony/SmsManager;",
      "method": "sendTextMessage",
      "descriptor": "(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Landroid/app/PendingIntent;Landroid/app/PendingIntent;)V"
    }
  ],
  "score": 1,
  "label": ["location", "collection"]
}

Step 5 — Assign score and labels

Score — always set 1 for a newly generated rule. The final score depends on how the behavior is distributed across real malware samples, so an analyst must study that distribution and adjust the score later.

Labels — use canonical labels from the existing rules repo:

collection, sms, network, file, command, control, reflection, telephony, accessibility service, record, wifi, location, screen, calllog, camera, applications, http, calendar, socket, evasion

Invent a new label only if none of the above apply — document it in your PR.

Step 6 — Generate and save the rule

Write the rule JSON to a temp file:

cat > /tmp/quark_candidate_rule.json << 'EOF'
{
  "crime": "...",
  "permission": ["..."],
  "api": [
    {"class": "...", "method": "...", "descriptor": "..."},
    {"class": "...", "method": "...", "descriptor": "..."}
  ],
  "score": 1,
  "label": ["..."]
}
EOF

Step 7 — Validate the rule

bash "${CLAUDE_PLUGIN_ROOT}/skills/rule-gen/scripts/validate_rule.sh" "<apk_path>" /tmp/quark_candidate_rule.json

If behaviors detected (exit 0): proceed to Step 8.

If zero behaviors (exit 1): return to Step 3 with the code snippet still in context. Revise the API pair or descriptor — common causes of zero results:

• Wrong class name (missing L prefix or ; suffix)
• Space in descriptor between parameters
• Method not found at this class level (may be in a parent class)
• Wrong method name (check the snippet again)

Maximum 3 attempts total. If still zero after 3 tries, tell the user what was tried and ask them to provide a more specific code snippet or a different API pair.

Step 8 — Output the final rule

Present the validated rule JSON and suggest a filename:

<crime_in_snake_case>.json

Example: send_location_via_sms.json

Tell the user: "Place this file in your rules directory (~/.quark-engine/quark-rules/rules/ for the default set, or a custom directory passed with -r)."