Merge pull request #1713 from mandiant/fix/issue-1711

record and show the analysis flavor

capa/ida/helpers.py

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

capa/main.py

@@ -29,6 +29,7 @@
 import colorama
 import tqdm.contrib.logging
 from pefile import PEFormatError
+from typing_extensions import assert_never
 from elftools.common.exceptions import ELFError
 
 import capa.perf
@@ -1022,6 +1023,13 @@ def collect_metadata(
     arch = get_arch(sample_path)
     os_ = get_os(sample_path) if os_ == OS_AUTO else os_
 
+    if isinstance(extractor, StaticFeatureExtractor):
+        flavor = rdoc.Flavor.STATIC
+    elif isinstance(extractor, DynamicFeatureExtractor):
+        flavor = rdoc.Flavor.DYNAMIC
+    else:
+        assert_never(extractor)
+
     return rdoc.Metadata(
         timestamp=datetime.datetime.now(),
         version=capa.version.__version__,
@@ -1032,6 +1040,7 @@ def collect_metadata(
             sha256=sha256,
             path=str(Path(sample_path).resolve()),
         ),
+        flavor=flavor,
         analysis=get_sample_analysis(
             format_,
             arch,

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

@@ -121,13 +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=flavor_to_pb2(meta.flavor),
         analysis=capa_pb2.Analysis(
             format=meta.analysis.format,
             arch=meta.analysis.arch,
@@ -480,6 +490,15 @@ def scope_from_pb2(scope: capa_pb2.Scope.ValueType) -> capa.rules.Scope:
         assert_never(scope)
 
 
+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:
     return rd.Metadata(
         timestamp=datetime.datetime.fromisoformat(meta.timestamp),
@@ -491,6 +510,7 @@ def metadata_from_pb2(meta: capa_pb2.Metadata) -> rd.Metadata:
             sha256=meta.sample.sha256,
             path=meta.sample.path,
         ),
+        flavor=flavor_from_pb2(meta.flavor),
         analysis=rd.StaticAnalysis(
             format=meta.analysis.format,
             arch=meta.analysis.arch,

capa/render/proto/capa.proto

@@ -192,12 +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;
+  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
@@ -776,6 +793,7 @@ class Metadata(google.protobuf.message.Message):
     ARGV_FIELD_NUMBER: builtins.int
     SAMPLE_FIELD_NUMBER: builtins.int
     ANALYSIS_FIELD_NUMBER: builtins.int
+    FLAVOR_FIELD_NUMBER: builtins.int
     timestamp: builtins.str
     """iso8601 format, like: 2019-01-01T00:00:00Z"""
     version: builtins.str
@@ -785,6 +803,7 @@ class Metadata(google.protobuf.message.Message):
     def sample(self) -> global___Sample: ...
     @property
     def analysis(self) -> global___Analysis: ...
+    flavor: global___Flavor.ValueType
     def __init__(
         self,
         *,
@@ -793,9 +812,10 @@ class Metadata(google.protobuf.message.Message):
         argv: collections.abc.Iterable[builtins.str] | None = ...,
         sample: global___Sample | None = ...,
         analysis: global___Analysis | None = ...,
+        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", "sample", b"sample", "timestamp", b"timestamp", "version", b"version"]) -> None: ...
+    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: ...
 
 global___Metadata = Metadata
 

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,11 +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: 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)),