render: show analysis flavor

closes #1711

capa/ida/helpers.py

@@ -153,7 +153,7 @@ def collect_metadata(rules: List[Path]):
             sha256=sha256,
             path=idaapi.get_input_file_path(),
         ),
-        flavor="static",
+        flavor=rdoc.Flavor.STATIC,
         analysis=rdoc.StaticAnalysis(
             format=idaapi.get_file_type_name(),
             arch=arch,

capa/main.py

@@ -21,7 +21,7 @@
 import contextlib
 import collections
 from enum import Enum
-from typing import Any, Dict, List, Tuple, Literal, Callable, Optional
+from typing import Any, Dict, List, Tuple, Callable, Optional
 from pathlib import Path
 
 import halo
@@ -1023,11 +1023,10 @@ def collect_metadata(
     arch = get_arch(sample_path)
     os_ = get_os(sample_path) if os_ == OS_AUTO else os_
 
-    flavor: Literal["static", "dynamic"]
     if isinstance(extractor, StaticFeatureExtractor):
-        flavor = "static"
+        flavor = rdoc.Flavor.STATIC
     elif isinstance(extractor, DynamicFeatureExtractor):
-        flavor = "dynamic"
+        flavor = rdoc.Flavor.DYNAMIC
     else:
         assert_never(extractor)
 

capa/render/default.py

@@ -33,6 +33,7 @@ def render_meta(doc: rd.ResultDocument, ostream: StringIO):
         (width("md5", 22), width(doc.meta.sample.md5, 82)),
         ("sha1", doc.meta.sample.sha1),
         ("sha256", doc.meta.sample.sha256),
+        ("analysis", doc.meta.flavor),
         ("os", doc.meta.analysis.os),
         ("format", doc.meta.analysis.format),
         ("arch", doc.meta.analysis.arch),

capa/render/proto/__init__.py

@@ -25,7 +25,7 @@
 Alternatively, --pyi_out=. can be used to generate a Python Interface file that supports development
 """
 import datetime
-from typing import Any, Dict, Union, Literal
+from typing import Any, Dict, Union
 
 import google.protobuf.json_format
 
@@ -121,14 +121,23 @@ def scope_to_pb2(scope: capa.rules.Scope) -> capa_pb2.Scope.ValueType:
         assert_never(scope)
 
 
+def flavor_to_pb2(flavor: rd.Flavor) -> capa_pb2.Flavor.ValueType:
+    if flavor == rd.Flavor.STATIC:
+        return capa_pb2.Flavor.FLAVOR_STATIC
+    elif flavor == rd.Flavor.DYNAMIC:
+        return capa_pb2.Flavor.FLAVOR_DYNAMIC
+    else:
+        assert_never(flavor)
+
+
 def metadata_to_pb2(meta: rd.Metadata) -> capa_pb2.Metadata:
     assert isinstance(meta.analysis, rd.StaticAnalysis)
     return capa_pb2.Metadata(
         timestamp=str(meta.timestamp),
         version=meta.version,
         argv=meta.argv,
         sample=google.protobuf.json_format.ParseDict(meta.sample.model_dump(), capa_pb2.Sample()),
-        flavor=meta.flavor,
+        flavor=flavor_to_pb2(meta.flavor),
         analysis=capa_pb2.Analysis(
             format=meta.analysis.format,
             arch=meta.analysis.arch,
@@ -481,9 +490,13 @@ def scope_from_pb2(scope: capa_pb2.Scope.ValueType) -> capa.rules.Scope:
         assert_never(scope)
 
 
-def flavor_from_pb2(flavor: str) -> Literal["static", "dynamic"]:
-    assert flavor in ("static", "dynamic")
-    return flavor  # type: ignore
+def flavor_from_pb2(flavor: capa_pb2.Flavor.ValueType) -> rd.Flavor:
+    if flavor == capa_pb2.Flavor.FLAVOR_STATIC:
+        return rd.Flavor.STATIC
+    elif flavor == capa_pb2.Flavor.FLAVOR_DYNAMIC:
+        return rd.Flavor.DYNAMIC
+    else:
+        assert_never(flavor)
 
 
 def metadata_from_pb2(meta: capa_pb2.Metadata) -> rd.Metadata:

capa/render/proto/capa.proto

@@ -192,13 +192,19 @@ message MatchFeature {
   optional string description = 3;
 }
 
+enum Flavor {
+  FLAVOR_UNSPECIFIED = 0;
+  FLAVOR_STATIC = 1;
+  FLAVOR_DYNAMIC = 2;
+}
+
 message Metadata {
   string timestamp = 1;  // iso8601 format, like: 2019-01-01T00:00:00Z 
   string version = 2;
   repeated string argv = 3;
   Sample sample = 4;
   Analysis analysis = 5;
-  string flavor = 6;
+  Flavor flavor = 6;
 }
 
 message MnemonicFeature {

capa/render/proto/capa_pb2.pyi

@@ -43,6 +43,23 @@ ADDRESSTYPE_DN_TOKEN_OFFSET: AddressType.ValueType  # 5
 ADDRESSTYPE_NO_ADDRESS: AddressType.ValueType  # 6
 global___AddressType = AddressType
 
+class _Flavor:
+    ValueType = typing.NewType("ValueType", builtins.int)
+    V: typing_extensions.TypeAlias = ValueType
+
+class _FlavorEnumTypeWrapper(google.protobuf.internal.enum_type_wrapper._EnumTypeWrapper[_Flavor.ValueType], builtins.type):
+    DESCRIPTOR: google.protobuf.descriptor.EnumDescriptor
+    FLAVOR_UNSPECIFIED: _Flavor.ValueType  # 0
+    FLAVOR_STATIC: _Flavor.ValueType  # 1
+    FLAVOR_DYNAMIC: _Flavor.ValueType  # 2
+
+class Flavor(_Flavor, metaclass=_FlavorEnumTypeWrapper): ...
+
+FLAVOR_UNSPECIFIED: Flavor.ValueType  # 0
+FLAVOR_STATIC: Flavor.ValueType  # 1
+FLAVOR_DYNAMIC: Flavor.ValueType  # 2
+global___Flavor = Flavor
+
 class _Scope:
     ValueType = typing.NewType("ValueType", builtins.int)
     V: typing_extensions.TypeAlias = ValueType
@@ -786,7 +803,7 @@ class Metadata(google.protobuf.message.Message):
     def sample(self) -> global___Sample: ...
     @property
     def analysis(self) -> global___Analysis: ...
-    flavor: builtins.str
+    flavor: global___Flavor.ValueType
     def __init__(
         self,
         *,
@@ -795,7 +812,7 @@ class Metadata(google.protobuf.message.Message):
         argv: collections.abc.Iterable[builtins.str] | None = ...,
         sample: global___Sample | None = ...,
         analysis: global___Analysis | None = ...,
-        flavor: builtins.str = ...,
+        flavor: global___Flavor.ValueType = ...,
     ) -> None: ...
     def HasField(self, field_name: typing_extensions.Literal["analysis", b"analysis", "sample", b"sample"]) -> builtins.bool: ...
     def ClearField(self, field_name: typing_extensions.Literal["analysis", b"analysis", "argv", b"argv", "flavor", b"flavor", "sample", b"sample", "timestamp", b"timestamp", "version", b"version"]) -> None: ...

capa/render/result_document.py

@@ -7,6 +7,7 @@
 # See the License for the specific language governing permissions and limitations under the License.
 import datetime
 import collections
+from enum import Enum
 from typing import Dict, List, Tuple, Union, Literal, Optional
 
 from pydantic import Field, BaseModel, ConfigDict
@@ -120,12 +121,17 @@ class DynamicAnalysis(Model):
 Analysis: TypeAlias = Union[StaticAnalysis, DynamicAnalysis]
 
 
+class Flavor(str, Enum):
+    STATIC = "static"
+    DYNAMIC = "dynamic"
+
+
 class Metadata(Model):
     timestamp: datetime.datetime
     version: str
     argv: Optional[Tuple[str, ...]]
     sample: Sample
-    flavor: Literal["static", "dynamic"]
+    flavor: Flavor
     analysis: Analysis
 
 

capa/render/verbose.py

@@ -92,6 +92,7 @@ def render_static_meta(ostream, doc: rd.ResultDocument):
         os                   windows
         format               pe
         arch                 amd64
+        analysis             static
         extractor            VivisectFeatureExtractor
         base address         0x10000000
         rules                (embedded rules)
@@ -110,6 +111,7 @@ def render_static_meta(ostream, doc: rd.ResultDocument):
         ("os", doc.meta.analysis.os),
         ("format", doc.meta.analysis.format),
         ("arch", doc.meta.analysis.arch),
+        ("analysis", doc.meta.flavor),
         ("extractor", doc.meta.analysis.extractor),
         ("base address", format_address(doc.meta.analysis.base_address)),
         ("rules", "\n".join(doc.meta.analysis.rules)),
@@ -154,6 +156,7 @@ def render_dynamic_meta(ostream, doc: rd.ResultDocument):
         ("os", doc.meta.analysis.os),
         ("format", doc.meta.analysis.format),
         ("arch", doc.meta.analysis.arch),
+        ("analysis", doc.meta.flavor),
         ("extractor", doc.meta.analysis.extractor),
         ("rules", "\n".join(doc.meta.analysis.rules)),
         ("process count", len(doc.meta.analysis.feature_counts.processes)),